<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
	<meta http-equiv="content-type" content="text/html;charset=UTF8">
	<title>NairnFEAMPMViz Help</title>
<style type="text/css">
h1 { font-family: Arial, "Lucida Grande", Helvetica, Swiss, Geneva, SunSans-Regular;
	font-size: 16pt;
	background-color: #CCCCCC;
	font-weight: bold;
	padding: 6pt; }
h2 { font-family: Arial, "Lucida Grande", Helvetica, Swiss, Geneva, SunSans-Regular;
	font-size: 14pt;
	margin-left: 3pt;
	background-color: #CCCCCC; }
h3 { font-family: Arial, "Lucida Grande", Helvetica, Swiss, Geneva, SunSans-Regular;
	font-size: 12pt;
	margin-left: 3pt;
	color: #005500;}
h4 { font-family: Arial, "Lucida Grande", Helvetica, Swiss, Geneva, SunSans-Regular;
	font-size: 12pt;
	margin-left: 9pt;
	color: #005555;
	font-style: italic;
	font-weight: normal;}
p { font-family: Arial, "Lucida Grande", Helvetica, Swiss, Geneva, SunSans-Regular;
	font-size: 12pt;
	margin-top: 0pt;
	margin-left: 12pt;
	margin-bottom: 6pt; }
ul { font-family: Arial, "Lucida Grande", Helvetica, Swiss, Geneva, SunSans-Regular;
	font-size: 12pt;
	list-style-image: Bullet.png;
	margin-top: 0pt;
	margin-bottom: 6pt;
	margin-left: 28pt; }
ul li { margin-top: 0pt;
	margin-bottom: 3pt; }
ol { font-family: Arial, "Lucida Grande", Helvetica, Swiss, Geneva, SunSans-Regular;
	font-size: 12pt;
	margin-left: 28pt;
	margin-top: 0px;
	margin-bottom: 0px; }
ol li { margin-top: 0px;
	margin-bottom: 3pt; }
img { vertical-align: middle; }
hr { margin-top: 0pt;
	margin-left: 0pt;
	margin-right: 6pt;
	padding: 0pt; }
code { font-size: 12pt; }
pre { margin-left: 24pt;
	font-size: 12pt;
	line-height: normal;
	font-family: Courier; }
dl { margin-left: 12pt; }
dt {font-family: "Courier";
	font-size: 12pt; }
dd { font-family: Arial, "Lucida Grande", Helvetica, Swiss, Geneva, SunSans-Regular;
	font-size: 12pt; }
table { font-family: Arial, "Lucida Grande", Helvetica, Swiss, Geneva, SunSans-Regular;
	font-size: 10pt;
	margin-top: 0pt;}
</style>
</head>

<body>

<div id="pagetitle"><h1>NairnFEAMPMViz Commands Language</h1></div>

<p><b>NairnFEAMPMViz</b> has a built-in <a href="#language">interpretive language</a> for programmatically setting up FEA or MPM calculations (and for running <a href="scripting.html">control scripts</a>). This section has a list of all language commands for FEA and MPM calculations. The commands are grouped by logical section. Within each section, they are listed by typical order of use (when possible). 
</p>

<p>The scripting <a href="#language">language</a> is based on the corresponding language in the NairnFEAMPM Mac application (and <a href="#compatible">nearly identical</a> to that language). The documentation listed below lists all the commands. This documentation is brief and just defines each command and the meaning of its arguments. The user is expect to be familiar with the scripting commands to set up FEA or MPM calculations, which is more fully documented on the <a href="http://osupdocs.forestry.oregonstate.edu/index.php/Main_Page">OSUPDocs wiki</a>. In other words, this help is meant to serve as a brief reference for when you do not have on-line access.</p>

<h2><a name="cindex"></a>Documentation Outline</h2>

<p>To begin writing scripts, first read the <a href="#language">Language Reference</a> section that defines the format of the scripting language. Next, see the various sections for each type of analysis. For FEA analysis, the groupings are:</p>

<ul>
<li><a href="#header">Main Analysis Header</a> commands</li>
<li><a href="#feamesh">Defining the FEA Mesh</a> commands</li>
<li><a href="#feacracks">Cracks in FEA Mesh</a> command</li>
<li><a href="#materials">Defining Materials</a> commands</li>
<li><a href="#feabcs">Boundary Condition</a> commands</li>
<li><a href="#thermalfea">Thermal Calculation</a> commands</li>
<li><a href="#xml">XML Insertion</a> commands</li>
</ul>

<p>For MPM calculations, the groupings are:</p>

<ul>
<li><a href="#header">Main Analysis Header</a> commands</li>
<li><a href="#mpmheader">MPM Analysis Header</a> commands</li>
<li><a href="#archive">Archiving Option</a> commands</li>
<li><a href="#grid">Defining the MPM Grid and Material Points</a> commands</li>
<li><a href="#materials">Defining Materials</a> commands</li>
<li><a href="#cracks">Explicit Crack</a> commands</li>
<li><a href="#mmmode">Multimaterial MPM</a> commands</li>
<li><a href="#thermal">Thermal Calculation</a> commands</li>
<li><a href="#conc">Diffusion Calculation</a> command</li>
<li><a href="#poro">Poroelasticity Calculation</a> command</li>
<li><a href="#bconds">Boundary Condition</a> commands</li>
<li><a href="#gravity">Gravitational Field</a> commands</li>
<li><a href="#custom">Custom Task</a> commands</li>
<li><a href="#xml">XML Insertion</a> commands</li>
</ul>

<p>A few <a href="#deprecate">deprecated commands</a> should no longer be used. This documentation explains their functions, if encountered, and explains how to replace them with new commands.</p>

<h2><a name="language"></a>Language Reference</h2>

<p>This sections describes the basic syntax of the scripting language:</p>

<ul>
<li><a href="#linesyntax">Line Syntax</a></li>
<li><a href="#varexp">Variables and Expressions</a></li>
<li><a href="#atexp">"At" Expressions</a></li>
<li><a href="#conditionals">Conditionals</a></li>
<li><a href="#repeat">Repeat Loops</a></li>
<li><a href="#subs">Subroutines</a></li>
<li><a href="#debug">Additional Built-In Commands</a></li>
<li><a href="#compatible">Comparison to NairnFEAMPM Language</a></li>
</ul>


<h3><a name="linesyntax"></a>Line Syntax</h3>

<p>Each line of scripting commands has the format:</p>
<pre>
Command #1,#2,#3,#4,...
</pre>
<p>where <code>Command</code> is the command and #1, #2, <i>etc</i>., are arguments to the command. The command
must be separated from the arguments by a space. The arguments must be separated for each other by commas.
Leading and trailing spaces in arguments are ignored. Blank lines are ignored.
Lines whose first non-blank character is &quot;!&quot; are comments and are also ignored.
</p>

<p>Any argument to any command can be a number, a string, or an expression. Arguments that expect numeric values can use string expressions provided those expressions evaluate to a string containing only a number. See next section for details on expressions.</p>

<h3><a name="varexp"></a>Variables and Expressions</h3>

<p>The commands can define variables that contain numeric or string values. Variable names must begin
in a letter or #, be followed by only letters, numbers and underscores, and optionally end in "$" (for backward compatibility). You create variables using the Set command:</p>
<pre>
Set var = expression
</pre>
<p>where <code>var</code> is any valid variable and <code>expression</code> is any expression. The &quot;Set&quot; command is
optional and generally not used; <i>i.e.</i>, any line with variable name followed by equals sign is assumed to be a &quot;Set&quot; command:</p>
<pre>
var = expression
</pre>

<p>Array variables are allowed and initialized using</p>
<pre>
var[indexExpression] = expression
</pre>
<p>where square brackets index the array index. The <code>indexExpression</code> can be an expression that evaluates to an integer. Multi-dimensional arrays can be used with more bracketed expressions:</p>
<pre>
var[expr1][expr2]...[exprn] = expression
</pre>
<p>where each expression in the square brackets are expressions that evaluate to integers.</p>

<h4><a name="numexprs"></a>Numeric Expressions</h4>

<p>Numeric expressions use standard operators (+, -, *, /, ^, and %) with standard precedences
unless grouped by parentheses. The text <code>pi</code> is set to the constant &pi; and can be used in expressions. An expression can use the following math
functions:</p>

 <ul>
 <li><code>sin(x)</code> - sine of x in radians</li>
 <li><code>cos(x)</code> - cosine of x in radians</li>
 <li><code>tan(x)</code> - tangent of x in radians</li>
 <li><code>asin(x)</code> - inverse sine with result in radians</li>
 <li><code>acos(x)</code> - inverse cosine with result in radians</li>
 <li><code>atan(x)</code> - inverse tangent with result in radians</li>
 <li><code>sinh(x)</code> - hyperbolic sine</li>
 <li><code>cosh(x)</code> - hyperbolic cosine</li>
 <li><code>tanh(x)</code> - hyperbolic tangent</li>
 <li><code>exp(x)</code> - exponential</li>
 <li><code>log(x)</code> - natural log</li>
 <li><code>log10(x)</code> - log base 10</li>
 <li><code>sqrt(x)</code> - square root</li>
 <li><code>abs(x)</code> - absolute value</li>
 <li><code>int(x)</code> - integer part</li>
 <li><code>erf(x)</code> - error function.</li>
 <li><code>erfc(x)</code> - error function complement.</li>
 <li><code>sign(x)</code> - 1 if x is positive or 0 if it is negative</li>
 <li><code>sgn(x)</code> - -1 if x &lt;0, 0 if x=0, and +1 if x&gt;0</li>
 <li><code>ramp(A,x)</code> - 0 if x&lt; 0, Ax if 0&lt;x&lt;1, A if x&gt;1</li>
 <li><code>cosramp(A,x)</code> -  0 if x&lt; 0, (A/2)(1-cos(&pi;x)) if 0&lt;x&lt;1, A if x&gt;1</li>
 <li><code>box(A,x)</code> -  0 if x&lt; 0, A if 0&lt;x&lt;1, 0 if x&gt;1</li>
 <li><code>sinbox(A,x)</code> - 0 if x&lt; 0, A sin(&pi;x) if 0&lt;x&lt;1, 0 if x&gt;1</li>
 <li><code>tri(x)</code> - 1-|x| for -1 &lt; x &lt; 1, 0 otherwise</li>
 <li><code>rand(x)</code> - a random number between 0 and x.</li>
 </ul>

<h4>String Expressions</h4>

<p>String expressions can combine quoted strings and variables with the single operator &amp;. Numeric
variables can be used and they are converted to strings. You can also embed numeric expressions
(including numeric constants) within string expressions by enclosing them in parentheses.
The words <code>return</code> and <code>tab</code> can be used between operators to insert a return
or tab character into the string.</p>

<p>String expressions can use the following string functions. Each string function takes a single string expression as an argument. Some functions embed sub-arguments within the evaluated single string expression (note that string expressions cannot be used in <a href="#function">user defined functions</a> for input command files):</p>

<ul>
<li><code>length(s)</code> - number of characters in <code>s</code>.</li>
<li><code>words(s)</code> - number of words in <code>s</code>.</li>
<li><code>firstWord(s)</code> - first word of <code>s</code>.</li>
<li><code>lastWord(s)</code> - last word of <code>s</code>.</li>
<li><code>removeFirstWord(s)</code> - string with first word of <code>s</code> removed.</li>
<li><code>removeLastWord(s)</code> - string with last word of <code>s</code> removed.</li>
<li><code>trim(s)</code> - string with leading and trailing white space of <code>s</code> removed.</li>
<li><code>chars(c1\c2\s)</code> - returns characters <code>c1</code> to <code>c2</code> of <code>s</code> (the first character is 1). <code>c1</code> defaults to 1 (if omitted ) and <code>c2</code> defaults to length of <code>s</code> (if omitted or larger). Thus <code>char(c1\s)</code> gets character 1 to the end and <code>char(\c2\s)</code> gets character 1 through <code>c2</code>. Either  <code>c1</code> or  <code>c2</code> can be &lt;= 0 to indicate character relative to <code>s</code> end (0 is end, -1 in one before end, <i>etc.</i>).</li>
<li><code>word(w1\s)</code> - returns word <code>w1</code> of <code>s</code> (<code>w1</code> can be &lt;= 0 to indicate word relative to end where 0 is last word, -1 in second to last, <i>etc.</i>). Returns empty result if word number is out of range for <code>s</code>.</li>
<li><code>offset(s1\c1\s)</code> - returns offset of string <code>s1</code> in <code>s</code> at or after character <code>c1</code> (the first character is character 1) or returns 0 if string <code>s1</code> is not found. <code>c1 can</code> be omitted to find <code>s1</code> any place in <code>string</code>. The search is case insensitive.</li>
<li><code>replace(s1\s2\s)</code> - returns string where all occurrences of string <code>s1</code> in <code>s</code> are replaced with string <code>s2</code>. <code>s2</code> may be omitted to delete all occurrences of string <code>s1</code>.</li>
<li><code>upperCase(s)</code> - convert <code>s</code> to upper case.</li>
<li><code>lowerCase(s)</code> - convert <code>s</code> to lower case.</li>
<li><code>titleCase(s)</code> - convert <code>s</code> to have capitalized words.</li>
</ul>

<p>To omit the first subargument in <code>chars()</code>, <code>offset()</code>, or <code>replace()</code>, start with a back slash (<i>e.g.</i>, <code>chars(\c2\s)</code>). To omit the second argument, you can either omit it and its backslash (<i>e.g.</i>, <code>chars(c1\s)</code>), but if <code>string</code> might contain a backslash, it is better to just omit the subargument (<i>e.g.</i>, <code>chars(c1\\s)</code>).</p>

<h4>Expression Update Shortcut</h4>

<p>As a short cut, the command</p>
<pre>
var {op}= expression
</pre>
<p>is equivalent to</p>
<pre>
var = var{op}(expression)
</pre>
<p>where <code>{op}</code> is any valid operator (but note that when <code>{op}</code> is &amp;, the expression is not surrounded by parentheses)</p>

<h3><a name="atexp"></a>"At" Expressions</h3>

<p>Any place a variable can be used, it can be replaced by an "at" expression beginning in an '@' sign and containing specific items separated by periods, such as "<code>@key.TopLeft.x</code>" to evaluate to the x value of the key point named "TopLeft". These expressions are used to allow a script to read properties of objects created earlier in the script. The currently supported "at" expressions for FEA and MPM calculations are:</p>
<ul>
<li><code>@key.ID.prop</code> - read a property of a <a href="#keypoint">keypoint</a> where "ID" is replaced by ID of the key point. The possible properties to replace "prop" are "x" and "y" to give x and y coordinates of the key point.</li>
<li><code>@path.ID.prop</code> - read a property of a <a href="#path">path</a> whereis  "ID" replaced by ID of the path. The possible properties to replace "prop" are "intervals" (number of intervals long the path), "ratio" (the ratio setting for the path), and "first", "middle" or "last" (for ID of the first, middle or last key point; if the path has only two key points the "middle" will be empty string).</li>
</ul>
<p>Any subelement of an "at" expression can be replaced by a string expression (as long as it does not include a period), such as:</p>
<pre>
#id = "BotLeft"
x = @key.#id.x
</pre>
<p><a href="scripting.html">Control scripts</a> support some additional "at" expressions.</p>

<h3><a name="conditionals"></a>Conditionals</h3>

<p>Conditional blocks have the format:</p>
<pre>
if expr1 == expr2
  ...
else ifStr expr3 &lt; expr4
  ...
else ifDef var1
  ...
else ifNDef var2
  ...
else
  ...
endif
</pre>
<p>In the standard if, the expressions are compared by numeric comparison, unless one or
both are strings, in which case string comparison is used. The ifStr command forces string
comparison between the expressions. The comparison operators
are =, ==, &quot;is&quot;, !=, &gt;, &gt;=, &lt;, and &lt;=. For numbers, =, ==, and &quot;is&quot; are
the same. For strings, = and &quot;is&quot; are case insensitive comparisons
and == is case sensitive. An ifDef comparison is true if the variable name
given has been defined in at least one Set command. The ifNDef comparison is true if the variable
has not been defined in any Set command.</p>

<h3><a name="repeat"></a>Repeat Loops</h3>

<p>Repeat loops, which can be nested, have the format:</p>

<pre>
Repeat "#x",start,end,&lt;step&gt;
  (commands in the loop)
    ...
  break
    ...
  Repeat "#y",start,end,&lt;step&gt;
    (commands in nested loop)
      ...
    continue
      ...
    Repeat
      (commands in nested continuous loop)
        ...
      breakAll
        ...
    EndRepeat
  EndRepeat
EndRepeat
</pre>

<p>The first parameter is a loop variable  (it should be quoted and cannot be an array variable). The range and optional step size are
in the next three arguments. A <code>Repeat</code> command with no arguments will repeat forever.
The <code>break</code> command breaks the current loop. The <code>breakAll</code> command breaks out of all nested
loops. A <code>continue</code> command goes to next item in the current loop.</p>

<h3><a name="subs"></a>Subroutines</h3>

<p>The commands can include subroutines. All subroutines must be defined at the start of the commands (i.e., before any other commands) in the style:</p>

<pre>
Sub subname #arg1,#arg2,...,#argn
  (subroutine commands)
    ...
  return
    ...
EndSub
</pre>
<p>where</p>
<ul>
<li><code>subname</code> is the name of the subroutine. The names of all subroutines must be unique.</li>
<li><code>#arg1,#arg2,...,#argn</code> are any number of subroutine arguments. The name of each argument must be a valid variable name and must not be in quotes.</li>
<li>The subroutine ends with the <code>EndSub</code> command and execution will return to the line after the <code>GoSub</code> command that called the subroutine.</li>
<li>The <code>return</code> command can be used to exit a subroutine at any time before the its end.</li>
</ul>

<p>Once subroutines are defined, then can be called with</p>
<pre>
GoSub subname parm1,parm2,...parmn
</pre>
<p>where <code>subname</code> is the name of the subroutine and <code>parm1,parm2,...parmn</code> are any expressions. The total number of expressions must exactly match the number of arguments in the subroutine definition. The variables in the subroutine definition will be set equal to the values passed in the <code>GoSub</code> command.</p>

<p>Two notes on subroutines are:</p>
<ol>
<li>All variables are global variables. Thus subroutines can use variables set in the main commands and the main commands can access variables defined in the subroutines including subroutine arguments. If a subroutine argument matches a variable from the main commands, calling the subroutine will overwrite that value.</li>
<li>Subroutines can be nested which means subroutines can call any other subroutines with <code>GoSub</code> commands.</li>
</ol>

<h3><a name="debug"></a>Additional Built-In Commands</h3>

<p>The additional commands in this section are built-in to the interpretive language.
Their main use in FEA or MPM calculations are for debugging purposes.
They have some additional uses when writing <a href="scripting.html">control scripts</a>.</p>

<ul>
<li><code>Write epxr1,expr2,...</code><br>
Write each argument (string or number or expression) to the output console.
</li>
<li><code>Stop expr1,expr2,...</code><br>
Write each argument (string or number or expression) to
the output console and then stop the calculations.
</li>
<li><code>Clear</code><br>
Clear all text from the output console.
</li>
<li><code>Lines varName,start,end,expr</code><br>
Split the string in <code>expr</code> into lines. The results are stored in
<code>varName[1]</code>... and the number of lines found is stored in <code>varName[0]</code> (where <code>varName</code> argument is an quoted, non-array, valid, variable name). The command retrieves lines <code>start</code> to <code>end</code> (1 based). Either limit can be &le;0 to indicate that number of lines from the end (where 0 means to the end). For example: (<code>start</code>, <code>end</code>) = (1,0) gets all lines, (0,0) gets the last line only, and (-2,0) gets the last three lines.</li>
<li><code>Words varName,start,end,expr,&lt;split&gt;</code><br>
This command is the same as the <code>Lines</code> command except it splits <code>expr</code> into words, where words are character groupings separated by any number of white space characters. The white space characters include line ending characters. If you use the optional <code>split</code> argument, the <code>expr</code> will be split at the entered string. Note that using <code>split=" "</code> will delimit at all space characters, in contrast to no <code>split=</code> where multiple spaces on considered as a single delimiter.</li>
</ul>

<h3><a name="compatible"></a>Comparison to NairnFEAMPM Language</h3>

<p>The scripting language in NairnFEAMPMViz is nearly identical to the corresponding scripting commands in the Mac application NairnFEAMPM. In most cases any script written in one application will work in the other. The only known difference is:</p>
<ul>
<li>The main command on each line must be separated from arguments by a space and arguments must be delimited by commas. In NairnFEAMPM commands and arguments can be delimited by commas, spaces, or tabs.</li>
</ul>
<p>If you get an error message suggesting a command that looks valid is an invalid command, check the delimiter between the command name and the first parameter. The NairnFEAMPM Mac program will work with any delimiter, but the NairnFEAMPMViz app requires the delimiter after commands to be one or more spaces. If a parameter is misinterpreted, look at delimiters between the parameters. The NairnFEAMPM Mac program will work with any delimiter, but this NairnFEAMPMViz app requires commas."#000000"</p>

<p>|<a href="#cindex">Documentation Index</a>|</p>

<h2><a name="header"></a>Main Analysis Header</h2>

<p>These main header commands define the type of analysis (FEA or MPM), enter comments about the calculations, and control FEA output. The commands to pick analysis type are:</p>

<ul>
<li><code><a name="trackspin"></a>Analysis (type)</code><br>
Define type of analysis to be done; <code>(type)</code> can be following strings:
<ul>
<li>&quot;Plane Strain FEA&quot;</li>
<li>&quot;Plain Stress FEA&quot;</li>
<li>&quot;Axisymmetric FEA&quot;</li>
<li>&quot;Plane Strain MPM&quot;</li>
<li>&quot;Plain Stress FEA&quot;</li>
<li>&quot;Axisymmetric MPM&quot;</li>
<li>&quot;3D MPM&quot;</li>
<li>&quot;Plane Strain MPM+PS&quot;</li>
<li>&quot;Plain Stress FEA+PS&quot;</li>
<li>&quot;Axisymmetric MPM+PS&quot;</li>
<li>&quot;3D MPM+PS&quot;</li>
</ul>
The "+PS" options implement MPM with tracking of particle spin and they require use of <a href="http://osupdocs.forestry.oregonstate.edu/index.php/OSParticulas">OSParticulas</a>.</li>

<li><code><a name="trackspin"></a>ConsistentUnits &lt;(length)&gt;,&lt;(mass)&gt;,&lt;(time)&gt;</code><br>
Determines the units used for all input commands for length, mass and time. Only metric options are allowed as follows:
<ul>
<li><code>(length)</code> can be km, m, dm, cm, mm, um (or microns), or nm</li>
<li><code>(mass)</code> can be kg, g, mg, or ug</li>
<li><code>(time)</code> can be s (or sec), ms (or msec), or us</li>
</ul>
If no <code>ConsistentUnits</code> command is used, the input file is assumed be using "Legacy" units, are mostly millimeters, grams, and seconds, but not exclusively. You may need to check each specific command to make sure you provide parameters in the correct units. Click <a href="#units">here</a> to see table of "Legacy" units and other common units.
</li>
<li><code>Processors (num)</code><br>
Select number of processors (1 or more) for running parallel code (requires parallel versions
of the code engines).</li>
</ul>

<p>The commands to add annotation to the output files are:</p>

<ul>
<li><code>Name (name)</code><br>
Defines name of the person doing the analysis.</li>
<li><code>Title (title)</code><br>
Defines a title for the analysis.</li>
<li><code>Header<br>&nbsp;&nbsp;(lines of text)<br>EndHeader</code><br>
Enter an analysis description on multiple lines of text.</li>
<li><code>Comment (expr1),&lt;(expr2)&gt;,&lt;(expr3)&gt;...</code><br>
Add a comment to the analysis description by evaluating each expression in <code>(expr1)</code>, <i>etc.</i> (and there can be any number of them) and append to a line beginning in &quot;Comment:&quot; to the header description in the output file.</li>
</ul>

<p>This command, which is for FEA only, controls the results that are output in the results files:</p>

<ul>
<li><a name="output"></a><code>Output (prop1),(out1),&lt;(prop2),(out2)&gt;,...</code><br>
Select the desired output results for FEA calculations. The arguments appear in pairs. The first of each pair (<i>e.g.</i>, <code>(prop1)</code>) can be:
<ul>
<li>&quot;displacements&quot;</li>
<li>&quot;forces&quot;</li>
<li>&quot;elementstresses&quot;</li>
<li>&quot;nodalstresses&quot;</li>
<li>&quot;reactivities&quot; at fixed displacement boundary conditions</li>
<li>&quot;energy&quot; of each element</li>
</ul>
to include those results in output FEA results file. The second of each pair (<i>e.g.</i>, <code>(out1)</code>) can be &quot;yes&quot; or &quot;no&quot; to include or omit those results, or it can be &quot;selected&quot; to only include results for selected nodes and elements (see <a href="#select">Select</a>, <a href="#selectline">SelectLine</a>, and <a href="#selectpoint">SelectPoint</a> commands).</li>
</ul>

<p>|<a href="#cindex">Documentation Index</a>|</p>

<h2><a name="mpmheader"></a>MPM Analysis Header</h2>

<p>The MPM header commands define many features of MPM calculations. The following groups them by function in the MPM header.</p>

<h3>MPM Method and Simulation Timing</h3>

<ul>
<li><a name="mpmmethod"></a><code>MPMMethod (update),&lt;(method)&gt;</code><br>
Select MPM methods for the calculations. <code>(update)</code> is the update
method and it can be USF, USAVG (same as USAVG+) or USL (same as USL+ or SZS),
or USAVG-, or USL-. <code>(method)</code> selects the shape functions method
and it can be uGIMP (or GIMP), lCPDI (or CPDI), qCPDI, B2Spline, B2GIMP, B2CPDI, or Classic (or Dirac).</li>

<li>XPIC(k) and FMPM(k) Simulations: Two advanced MPM options are called XPIC(k) and FMPM(k). The provide noise reduction and stabilization without unwanted dissipation. Use the <a href="#XPICFMPM">PeriodicXPIC Custom Task</a> to use these methods in simulations.</li>

<li><code>TimeStep (step),&lt;(max)&gt;,&lt;(factor)&gt;</code><br>
Set MPM time step parameters. <code>(step)</code> is the time step in <a href="#units">alt time units</a>
(choose a high number to have the code pick time step based on material properties).
Optional <code>(max)</code> is the maximum time to stop the calculations
in <a href="#units">alt time units</a> (which can also be set in
the <a href="#maximumtime">MaximumTime command</a>).
The optional <code>(factor)</code> is the Courant-Friedrichs-Levy safety factor for
the code to adjust the time step
(which can also be set in the <a href="#cflfactor">CFLFactor command</a>).</li>

<li><a name="cflfactor"></a><code>CFLFactor (factor),&lt;(transFactor)&gt;</code><br>
Sets the Courant-Friedrichs-Levy safety factors for the code to adjust the time step. The first parameter
is for mechanics calculations while the second (optional) parameter is for transport equations. The defaults are both 0.5;
they should be less then 1 and may need to be less than 0.5.</li>

<li><a name="maximumtime"></a><code>MaximumTime (max)</code><br>
Set time the MPM calculations will stop in <a href="#units">alt time units</a>.</li>

<li><code>PtsPerElement (axis)</code>
Select number of material points along each axis in the grid (in <code>(axis)</code>). The supported options are 1 to 5 for 2D and 1 to 3 of 3D. The total number of points in the element will be square of the entered value in 2D and the cube in 3D.</li>

<li><code>CPDIrcrit (rcrit)</code>
One problem with lCPDI, qCPDI, or B2CPDI shape functions is that if a particle deforms too much, its' corners may extend beyond ghost rows into other patches used in parallel coding. If that becomes a problem, this parameter will restrict corner deformation to keep them within a single patch. Enter maximum allowed particle radius in <code>(rcrit)</code> in units of cell size. 
</ul>

<h3><a name="mhdamp"></a>Damping Commands</h3>

<p>Various damping options are explained in the <a href="http://osupdocs.forestry.oregonstate.edu/index.php/Damping_Options">OUSPDocs wiki</a>. They are activated with these commands.</p>

<ul>
<li><code>Damping (alphag)</code><br>
<code>PDamping (alphap)</code><br>
Select factors for damping based on grid velocity (<code>Damping</code>) or on particle velocities (<code>PDamping</code>); <code>(alphag)</code> and <code>(alphap)</code> can be a numeric value or a
<a href="#function">user-defined function</a> of time (in units of <a href="#units">1/time units</a>). </li>

<li><code>FeedbackDamping (gaing),&lt;(Tkg)&gt;,&lt;(maxAlphag)&gt;</code><br>
<code>PFeedbackDamping (gainp),&lt;(Tkp)&gt;,&lt;(maxAlphap)&gt;</code><br>
Select options for alternative damping of MPM particle velocities. The two commands base the damping on grid velocity (<code>FeedbackDamping</code>) or on particle velocities (<code>PFeedbackDamping</code>). The two commands have independent settings. The  <code>(gaing)</code> (or p) is feedback coefficient in units of <a href="#units">1/(length units)<sup>2</sup></a>. The optional <code>(Tkg)</code> (or p) is target kinetic energy (it can be
<a href="#function">user-defined function</a>) in micro joules. The optional
<code>(maxAlphag)</code> (or p) is maximum damping factor in units <a href="#units">1/time units</a> (default is to have no maximum).
</li>
</ul>

<h3><a name="mhother"></a>Other Options</h3>

<ul>
<li><code>ExtrapolateRigid &lt;(option)&gt;</code><br>
When this option is activated (with <code>(option)</code>="yes" or omitted), all <a href="materials.html#rigid">rigid material</a> particles that set boundary conditions for velocity, temperature, concentration, or pore pressure will extrapolate to the grid first and then set boundary conditions on those extrapolated values. It is normally used when the rigid particle values vary with position, such as loading in shear.</li>
<li><code>LeaveLimit (allow)</code><br>
Set number of particles allowed to leave the grid (in <code>(allow)</code>) before an analysis is stopped.
If command is omitted, the limit is 1% of the particles. Set to 1 to stop when the first particle leaves the grid.</li>
</ul>

<p>|<a href="#cindex">Documentation Index</a>|</p>

<h2><a name="archive"></a>Archiving Options</h2>

<p>Calculations results are saved in <a href="#parch">particle archives</a> or <a href="#garch">global archives</a>. These commands determined what results are saved in those archives.</p>

<h3><a name="parch"></a>Particle Archiving Options</h3>

<ul>
<li><code>Archive (path)</code><br>
Select archiving folder for MPM calculations as relative path from the output file.</li>

<li><code>ArchiveUnique (path)</code><br>
Same as Archive command excepts creates unique subfolder (with intervening numbers) to prevent overwriting of
previous results.</li>

<li><a name="atime"></a><code>ArchiveTime (time),&lt;(firstTime)&gt;,&lt;(props)&gt;</code><br>
Select archiving frequency for MPM calculations. <code>(time)</code> is the archiving time in <a href="#units">alt time units</a>.
The optional <code>(firstTime)</code> is the time to start archiving (in <a href="#units">alt time units</a>, default is 0).
The optional <code>(props)</code> forces archiving if <code>(props)</code> propagations and/or
debonds have occurred since the last archive (default is 0, which disables counting of propagations).<br/>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;To create custom archiving schemes with various archiving intervals, you can create archiving blocks by using multiple <code>ArchiveTime</code> commands. Each subsequent command adds a new block that archives with new <code>(time)</code> and <code>(props)</code> settings. The new block starts at the new command's <code>(firstTime)</code> parameter, which must be later than the start of the previous archiving block.
</li>

<li><a name="toarchive"></a><code>ToArchive (quant1),&lt;(quant2)&gt;,...</code><br>
Specify results to be archived in MPM calculations. The list can be in multiple arguments (<code>(quant1)</code>,
<code>(quant2)</code>, etc.) and/or in multiple <code>ToArchive</code> commands. The archiving options are:
<ul>
<li>velocity - particle velocity</li>
<li>stress - particle Cauchy stress</li>
<li>strain - particle total strain, which in combination with <code>rotstrain</code> gives full deformation gradient.</li>
<li>plasticstrain - an alternate particle strain (some materials provide plastic strains; others provide other data)</li>
<li>rotstrain - rotation strain is needed for visualization plots that transform particles. It is now automatically archived
whenever strain is archived (which means full deformation gradient is archived)</li>
<li>strainenergy - cumulative &sigma;.d(&epsilon;-&epsilon;<sub>res</sub>)</li>
<li>workenergy - cumulative &sigma;.d&epsilon;</li>
<li>heatenergy</li>
<li>plasticenergy</li>
<li><code>lp</code> - angular momentum due to particle spin (zero unless <a href="#trackspin">particle spin</a> is activated)</li>
<li><code>wp</code> - angular velocity due to particle spin (zero unless <a href="#trackspin">particle spin</a> is activated).</li>
<li>temperature</li>
<li>concentration or porepressure - concentration and gradients when doing diffusion calculations or pore pressure and gradients when doing poroelasticity calculations </li>
<li>jintegral - at crack tips</li>
<li>stressintensity - at crack tips</li>
<li>history1, history2, history3, history4 - up to four material-dependent history variables can be archived.</li>
<li>damagenormal - vector normal to damage plane in softening materials.</li>
<li>energybalance - research topic, not meant for general use</li>
<li>elementcrossings - number of times the particle as crossed element boundaries</li>
</ul>
Note that the NairnFEAMPMViz handles units when visualizing the above archived results and lets you pick alterniate length and time units.
</li>
</ul>

<h3><a name="garch"></a>Global Archiving Options</h3>

<ul>
<li><a name="globalarchive"></a><code>GlobalArchive (quant),&lt;(mat)&gt;</code><br>
Global results are average values over the particles. Specify global result to be archived in <code>(quant)</code> (see below). If <code>(mat)</code> is provided (as a material ID), the global result will be only for particles of that material.
<li><code>GlobalArchive (quant),(x),(y),&lt;(z)&gt;</code><br>
The input coordinates define location of a tracer particle. Whatever particle quantity is selected will be output to the global archive file for the single particle whose initial position is closest to the provided coordinates. The <code>(z)</code> value can omitted for 2D simulations; enter R-Z coordinates in <code>(x),(y)</code> for axisymmetric simulations.</li>
<li><code>GlobalArchiveTime (time)</code><br>
Specify time interval for archiving global results, <code>(time)</code> is the global archiving time in <a href="#units">alt time units</a>. If not specified, global archiving is done at the <a href="#atime">standard archiving time</a>.</li>
</ul>

<p>The global archiving quantities, listed by category are:</p>
<ul>
<li>Stresses
<ul>
	<li><code>sxx</code>, <code>syy</code>, <code>szz</code>, <code>sxy</code>, <code>sxz</code>, or <code>syz</code>
	 - average element of the stress tensor in <a href="#units">pressure units</a></li>
	<li><code>sRR</code>, <code>sZZ</code>, <code>sTT</code>, or <code>sRZ</code> - average element of the axisymmetric stress tensor in <a href="#units">pressure units</a> (synonyms for <code>sxx</code>, <code>syy</code>, <code>szz</code>, and <code>sxy</code>)</li>
</ul></li>

<li>Strains and Deformation
<ul>
	<li><code>exx</code>, <code>eyy</code>, <code>ezz</code>, <code>exy</code>, <code>exz</code>, or <code>eyz</code>
	 - average element of the total <a href="#gbiot">Biot</a> strain tensor in %</li>
	<li><code>eRR</code>, <code>eZZ</code>, <code>eTT</code>, or <code>eRZ</code>
	 - average element of the axisymmetric total <a href="#gbiot">Biot</a> strain tensor %
	 (synonyms for <code>exx</code>, <code>eyy</code>, <code>ezz</code>, and <code>exy</code>)</li>
	<li><code>exxe</code>, <code>eyye</code>, <code>ezze</code>, <code>exye</code>, <code>exze</code>, or <code>eyze</code>
	 - average element of the elastic <a href="#gbiot">Biot</a> strain tensor in %, which is total
	 <a href="#gbiot">Biot</a> strain minus plastic <a href="#gbiot">Biot</a> strain for plasticity materials</li>
	<li><code>eRRe</code>, <code>eZZe</code>, <code>eTTe</code>, or <code>eRZe</code>
	 - average element of the axisymmetric elastic <a href="#gbiot">Biot</a> strain tensor in %
	 (synonyms for <code>exxe</code>, <code>eyye</code>, <code>ezze</code>, and <code>exye</code>)</li>
	<li><code>exxp</code>, <code>eyyp</code>, <code>ezzp</code>, <code>exyp</code>, <code>exzp</code>, or <code>eyzp</code>
	 - average element of the plastic <a href="#gbiot">Biot</a> strain tensor in %</li>
	<li><code>eRRp</code>, <code>eZZp</code>, <code>eTTp</code>, or <code>eRZp</code>
	 - average element of the axisymmetric plastic <a href="#gbiot">Biot</a> strain tensor %
	 (synonyms for <code>exxp</code>, <code>eyyp</code>, <code>ezzp</code>, and <code>exyp</code>)</li>
	<li><code>Fij</code> (where <code>i</code> and <code>j</code> are <code>x</code>, <code>y</code>, or <code>z</code>) - any component of the total deformation gradient (absolute)</li>
	<li><code>Fij</code> (where <code>i</code> and <code>j</code> are <code>R</code> or <code>Z</code>) - any component of the total axisymmetric deformation gradient (absolute, synonyms for the <code>x</code> or <code>y</code>) versions.</li>
	<li><code>velx</code>, <code>vely</code>, or <code>velz</code> - average component of velocity in <a href="#units">velocity units</a></li>
	<li><code>velR</code> or <code>velZ</code> - average component of axisymmetric velocity in <a href="#units">velocity units</a> (synonyms for <code>velx</code> or <code>vely</code>)</li>
	<li><code>dispx</code>, <code>dispy</code>, or <code>dispz</code> - average component of displacement in <a href="#units">length units</a></li>
	<li><code>dispR</code> or <code>dispZ</code> - average component of axisymmetric displacement in <a href="#units">length units</a> (synonyms for <code>dispx</code> or <code>dispy</code>)</li>
</ul></li>

<li>Momenta
<ul>
	<li><code>px</code>, <code>py</code>, or <code>pz</code> - average component of momentum (in <a href="#units">linear momentum units</a>)</li>
	<li><code>pR</code> or <code>pR</code> - average component of axisymmetric momentum (in <a href="#units">linear momentum units</a>) (synonyms for <code>px</code> or <code>py</code>)</li>
	<li><code>Lx</code>, <code>Ly</code>, or <code>Lz</code> - average component of angular momentum (in <a href="#units">angular momentum units</a>) (note that only Lz is non-zero in 2D or axisymmetric calculations).</li>
	<li><code>Lpx</code>, <code>Lpy</code>, or <code>Lpz</code> - average component of particle spin angular momentum (in <a href="#units">angular momentum units</a>) (note that only Lpz is non-zero in 2D or axisymmetric calculations and the simulation must be <a href="#trackspin">tracking particle spin</a> for any component to be non zero).</li>
	<li><code>wpx</code>, <code>wpy</code>, or <code>wpz</code> - average component of particle spin velocity (in <a href="#units">1/time units</a>) (note that only wpz is non-zero in 2D or axisymmetric calculations and the simulation must be <a href="#trackspin">tracking particle spin</a> for any component to be non zero).</li>
</ul></li>

<li>Contact and Reaction Forces
<ul>
	<li><code>contactx</code>, <code>contacty</code>, or <code>contactz</code> - component of the total contact force on the grid for <a href="#mmmode">multimaterial mode</a> simulations when they include <a href="materials.html#rigid">rigid materials</a> that have <code>direction=8</code>. It is a sum of all contact forces for the rigid material on the object in <a href="#units">force units</a>.</li>
	<li><code>contactR</code> or <code>contactZ</code> - component of the total contact force per radian on the axisymmetric grid in <a href="#units">force units</a> (synonyms for <code>contactx</code> or <code>contacty</code>)</li>
	<li><code>reactionx</code>, <code>reactiony</code>, or <code>reactionz</code> - component of the reaction force at nodes with velocity boundary conditions in <a href="#units">force units</a>. If option <code>(mat)</code> specifies a material, the force will be for all velocity conditions created by that <a href="materials.html#rigid">rigid material</a>; if <code>(mat)</code> is omitted the force will sum all velocity boundary conditions (specified or created by rigid particles); if <code>(mat)</code> &lt; 0, the force will be only for <a href="#velbc">velocity boundary conditions</a> with that boundary condition ID.  When the <a href="#mhother"><code>ExtrapolateRigid</code></a> option is used, set <code>(material)</code> to -40 to get reaction force for all rigid materials (and in this mode it is not possible to separate forces on different rigid materials).</li>
	<li><code>reactionR</code> or <code>reactionZ</code> - component of the reaction force per radian at axisymmetric nodes with velocity boundary conditions in <a href="#units">force units</a> (synonyms for <code>reactionx</code> or <code>reactiony</code> and see those options for meaning of the <code>(mat)</code> option)</li>
</ul></li>

<li>Temperature and Heat
<ul>
	<li><code>temp</code> - average temperature (in K)</li>	
	<li><code>Heat Energy</code> - total heat energy in <a href="#units">energy units</a></li>
	<li><code>Friction Work</code> - total friction work converted into heat in <a href="#units">energy units</a>.</li>
	<li><code>heatWatts</code> - the heating force at nodes with velocity boundary conditions in <a href="#units">energy units/time units</a>. If <code>(mat)</code> specifies a material, the heating rate will be for all temperature conditions created by that rigid material; if<code>(mat)</code> is omitted the heating rate will sum all temperature boundary conditions (specified or created by that <a href="materials.html#rigid">rigid material</a>); if <code>(mat)</code> &lt; 0, the heating rate will be only for <a href="#tempbc">temperature</a> boundary conditions with that boundary condition ID.</li>
</ul></li>

<li>Thermodynamics Functions
<ul>
	<li><code>Work Energy</code> - total work energy in <a href="#units">energy units</a></li>
	<li><code>Kinetic Energy</code> - total kinetic energy in <a href="#units">energy units</a> on the particles</li>
	<li><code>Grid Kinetic Energy</code> - total kinetic energy in <a href="#units">energy units</a> on the grid</li>
	<li><code>Strain Energy</code> - total external work in <a href="#units">energy units</a></li>
	<li><code>Heat Energy</code> - total heat energy in <a href="#units">energy units</a></li>
	<li><code>Entropy</code> - total entropy in <a href="#units">energy/K units</a></li>
	<li><code>Plastic Energy</code> - total dissipated energy in <a href="#units">energy units</a></li>
	<li><code>Internal Energy</code> - sum of work and heat energy (U = w + q) in <a href="#units">energy units</a></li>
	<li><code>Helmholz Energy</code> - total Helmholz free energy (A = U - TS) in <a href="#units">energy units</a></li>
	<li><code>Interface Energy</code> - total energy associated with cracks having imperfect interfaces in <a href="#units">energy units</a>.</li>
</ul></li>

<li>Damping Terms 
<ul>
	<li><code>alpha</code> - the total grid damping coefficient, &alpha;, which evolves when using feedback damping (in <a href="#units">1/time units</a>c)</li>
	<li><code>palpha</code> - the total particle damping coefficient, &alpha;, which evolves when using particle feedback damping (in <a href="#units"> 1/timeunits</a>c)</li>
</ul></li>

<li>Damage Mechanics
<ul>
	<li><code>Decohesion</code> - This quantity will result in a second global archive file (with extension .decohn) that will have a tab-delimited list of information about particle decohesions when using softening materials. Without this option, decohesion information is written to the main output file. With this option, all that output is diverted to a file and it includes some additional information. It is most useful in 3D simulations with lots of decohesion.</li>
</ul></li>

<li>Other Properties
<ul>
	<li><code>concentration</code> or <code>porepressure</code> - weight fraction concentration when doing diffusion calculations or pore pressure in <a href="#units">pressure units</a> when doing poroelasticity calculations.</li>	
	<li><code>Step number</code> - the current MPM step number</li>
	<li><code>Elapsed time</code> - elapsed clock time for the current calculation (in secs)</li>
	<li><code>CPU time</code> - total CPU time for the current calculation (in secs)</li>
</ul></li>
</ul>
<p><a name="gbiot">Note:</a> when global archiving of strains, they are calculated as a Biot strain in the current configuration.
The Biot strain is defined is <B>V-I</B> where <B>V</B> is the left-stretch tensor.
This strain is also the Seth-Hill strain with m=1/2 in current configuration. For small strain problems it is
equivalent to the small strain tensor.
</p>

<p>|<a href="#cindex">Documentation Index</a>|</p>

<h2><a name="materials"></a>Defining Materials</h2>

<p>The one command in this section is used to enter properties for materials used in the calculations.</p>

<ul>
	<li><a name="material"></a><code>Material (id),(name),(type)<br>
	&nbsp;&nbsp;(commands to define properties)<br>
	Done</code><br>
	Define a material type, a traction law, and imperfect interface. For more details see the <a href="materials.html">materials help topic</a> (or click the "file cabinet" icon in this window's tool bar).</li>
</ul>

<p>|<a href="#cindex">Documentation Index</a>|</p>

<h2><a name="grid"></a>Defining the MPM Grid with Material Points</h2>

<h3>Creating MPM Background Grid</h3>

<p>These commands are used to create the MPM background grid:</p>

<ul>
<li><a name="gridhoriz"></a><code>GridHoriz (num),&lt;sym1&gt;,&lt;sym1dir&gt;,&lt;sym2&gt;</code><br>
Set horizontal or x-direction MPM grid parameters (r direction is axisymmetric); <code>(num)</code> is the number of cells in that direction. The remaining parameters set optional symmetry planes at the minimum or maximum edge along the x (or r) axis (in <a href="#units">length units</a>). Symmetry planes automatically create all boundary conditions needed for the plane and provide special "symmetry" conditions with improved accuracy over creating your own boundary conditions. <code>(sym1)</code> is x value for the symmetry plane; <code>(sym1dir)</code> is -1 or 1 for the <code>(sym1)</code> plane to be at the minimum or maximum edge along the x axis; <code>(sym2)</code> creates a symmetry plane on the edge opposite to the <code>(sym1)</code> plane.</li>

<li><a name="gridvert"></a><code>GridVert (num),&lt;sym1&gt;,&lt;sym1dir&gt;,&lt;sym2&gt;</code><br>
Set vertical or y-direction MPM grid parameters (Z direction is axisymmetric). The parameters are as explained for the <a href="#gridhoriz"><code>GridHoriz</code> command</a> (except for a different axis).</li>

<li><a name="griddepth"></a><code>GridDepth (num),&lt;sym1&gt;,&lt;sym1dir&gt;,&lt;sym2&gt;</code><br>
Set depth or z-direction MPM grid parameters. The parameters are as explained for the <a href="#gridhoriz"><code>GridHoriz</code> command</a> (except for a different axis).</li>

<li><code>GridThickness (thick)</code><br>
Set thickness for 2D MPM grid (in <a href="#units">length units</a>) to <code>(thick)</code>. It is only needed for some features in 2D planar calculations.</li>

<li><code>GridRect (xmin),(xmax),(ymin),(ymax),&lt;(zmin)&gt;,&lt;(zmax)&gt;</code><br>
Set rectangle for 2D MPM grid or box for 3D MPM. <code>(xmin)</code>, <code>(xmax)</code>, <code>(ymin)</code>, and <code>(ymax)</code> are the axis ranges for the rectangle (or R and Z ranges if axisymmetric). <code>(zmin)</code> and <code>(zmax)</code> are for z minimum
and z maximum for 3D calculations (in <a href="#units">length units</a>). Use <a href="#gridhoriz">GridHoriz</a>,
<a href="#gridvert">GridVert</a>, and <a href="#griddepth">GridDepth</a> to set number of
cells in each direction before using this command.</li>

<li><code>Element (type)</code><br>
Define type of element to use in the MPM background grid. Currently (type) can only be &quot;4 Node Quadrilateral&quot; (or 2) for 2D or axisymmetric MPM and can only be &quot;8 Node Brick&quot; (or 7) for 3D MPM. This command is not needed for MPM calculations.</li>

</ul>

<p>These commands are used to define material points within that grid by using shape commands.</p>
<h3>Creating Material Points with Shape Commands</h3>

<p>These commands are used to define material points within that grid by using shape commands.</p>

<ul>
<li><a name="regionmpm"></a><code>Region (mat),(velx),(vely),(velzOrThick),&lt;(prop,value)&gt;<br>
&nbsp;&nbsp;(one optional <a href="#transform">Transform</a> command)<br>
&nbsp;&nbsp;(optional <a href="#angularmom0">AngularMom0</a> commands)<br>
&nbsp;&nbsp;(series of <a href="#shape2D">2D</a> or <a href="#shape3D">3D</a> shape commands)<br>
&nbsp;&nbsp;(optional <a href="#rotatempm">Rotate</a> commands)<br>
EndRegion</code><br>
Define a region for creating material points within the union of the subordinate <a href="#shape2D">shape commands</a>.
<code>(mat)</code> is material ID. (<code>velx,velz</code>) are velocities in x and y
direction  (in <a href="#units">velocity units</a>). For 2D, <code>(velzOrThick)</code> is thickness in
<a href="#units">length units</a>, but for 3D it is velocity in z direction (in <a href="#units">velocity units</a>).
The velocities can be numerical values or <a href="#function">user-defined functions</a> of particle position.
The optional <code>(prop,value)</code> pairs to set some initial property of the materials.
The <code>(prop)</code> options are "angle" (for material rotation about z axis in degrees),
"temp" (for temperature in K), "conc" (for particle concentration potential), and "pp" (for particle concentration potential).</li>

<li><a name="holempm"></a><code>Hole<br>
&nbsp;&nbsp;(series of <a href="#shape2D">2D</a> or <a href="#shape3D">3D</a> shape commands)<br>
commands)<br>
EndHole</code><br>
Define a region for creating a hole that will not be assigned material points.
The hole is defined by the union of the subordinate <a href="#shape2D">shape commands</a>.</li>

<li><a name="transform"></a><code>Transform (angZ),&lt;(Tx)&gt;,&lt;(Ty)&gt;,&lt;(Ox)&gt;,&lt;(Oy)&gt;,&lt;(angY)&gt;,&lt;(angZ2)&gt;,&lt;(Tz)&gt;,&lt;(Ozx)&gt;</code><br>
This command will rotate all particles in the shape by ZYZ rotation scheme using angles <code>(angZ)</code>,
<code>(angY)</code>, and <code>(angZ2)</code>, respectively, about an origin at (<code>(Ox),(Oy),(Oz)</code>) and then
translate them by (<code>(Tx),(Ty),(Tz)</code>). The rotation is rotating the particle shape and not the particle
material property axes. Note that when regions are transformed, the particles are placed wherever they appear on the
grid including on top other particles inserted in other commands. In other words, when using this option,
the user is responsible for insuring that particles do not overlap. All parameters are optional; those omitted are set to zero.
The first five commands are for 2D simulations. The last four add more parameters needed for 3D simulations.
</li>

<li><a name="rotatempm"></a><code>Rotate (axis),(angle),&lt;(axis),(angle)&gt;,...</code><br>
To rotate, in order, about each axis <code>(axis)</code> (x,y,z,1,2,or 3) by each angle <code>(angle)</code>
(can be function) for materials in the current <a href="#regionmpm">region</a>.
The <code>(axis)</code> can alternatively be "reset" to remove all previous rotations in the current
<a href="#regionmpm">region</a>. Up to three rotations in 3D calculations can either be entered in
one command or in a series of commands.</li>

<li><a name="angularmom0"></a><code>AngularMom0 (Lp0z)</code> (in 2D)<br>
<code>AngularMom0 (Lp0x),(Lp0y),(Lp0z)</code> (in 3D)<br>
To set the initial angular momentum per unit mass in <a href="#units">(length units)<sup>2</sup>/time units</a> of all particles in the current <a href="#regionmpm">region</a>, including particles created in shape commands <i>before</i> the <code>AngularMom0</code> command. The values can be numeric or <a href="#function">user-defined functions</a> of particle position. This command is setting angular momentum and not angular velocity. The setting to get a particular angular velocity (&omega; radians per <a href="#units">tim units</a>) for particles at typical starting positions would be:
<ul>
<li>2D, 4 particles per cell: L<sub>p,z</sub> = (3/16)(dx<sup>2</sup> + dy<sup>2</sup>)&omega;</li>
<li>2D, 1 particle per cell: L<sub>p,z</sub> = (1/4)(dx<sup>2</sup> + dy<sup>2</sup>)&omega;</li>
</ul>
where dx and dy are cell dimensions for the grid cell containing the particle. For 3D simulations, the equations for each axis are the same except each one depends on cell dimensions in the other two directions (e.g., L<sub>p,x</sub> depends on dy and dz).</li>

</ul>

<h3>Creating Material Points with Images</h3>

<p>These commands are used to define material points using an image (in 2D) or a stack of images (in 3D).</p>

<ul>
<li><a name="bmpregionmpm"></a><code>BMPRegion (path),(width),&lt;(height)&gt;,&lt;(scheme)&gt;,&lt;(anglesPath)&gt;,...<br>
&nbsp;&nbsp;(One <a href="#origbmpmpm">Origin</a> command and <a href="#intensitympm">Intensity</a> commands)<br>
EndRegion</code><br>
Create material from an image in a BMP file with <code>(path)</code> having the path for image file name. <code>(width)</code> and <code>(height)</code> give width and height of the image (in <a href="#units">length units</a>). Either can be negative to enter <a href="#units">length unit</a> per pixel instead of absolute picture size. If either one is omitted, the other one is calculated by the aspect ratio of the image in the file (to omit <code>(width)</code> or <code>(height)</code> when needed for parameter alignment, the number should be more negative than -1e8).<br>
The optional <code>(scheme)</code> and 1 to 3 <code>(anglesPath)</code>s gives paths to 1 to 3 additional BMP files (of the same size) whose gray scale values determine one Euler angle for particles covered by the image. For 2D  simulations the <code>(scheme)</code> must be "Z" and the one BMP files gives rotation angle about the z axis (in fact, for 2D, the <code>(scheme)</code> argument can be omitted). For 3D, the scheme can be any 1 axis, 2 axes, or 3 axes beginning in "Z" (<i>e.g.</i>, "ZYZ") to specify Euler angle method and gray scales in the file determine the angles. For details on rotation angles see <a href="">OSUPDocs details</a>. Mapping of gray scale to angle is done with 1 to 3 <code>Intensity</code> commands.</li>

<li><a name="intensitympm"></a><code>Intensity (mat),(imin),(imax),&lt;(prop,value)&gt;,...</code><br>
Map pixel gray scale values in <a href="#bmpregionmpm">BMPRegion</a> in the range <code>(imin)</code> to <code>(imax)</code>
to material in <code>(mat)</code>. The optional pairs <code>(prop,value)</code> can set
initial material point properties with (prop) options of:
<ul>
<li>"thick" for particle thickness in <a href="#units">length units</a>.</li>
<li>"angle" for rotation angle of the material about the z axis in degrees.</li>
<li>"temp" for particle temperature in C (or K).</li>
<li>"vx" for particle x-direction velocity in <a href="#units">velocity units</a>.</li>
<li>"vy" for particle y-direction velocity in <a href="#units">velocity units</a>.</li>
<li>"vz" for particle z-direction velocity in <a href="#units">velocity units</a> (for 3D MPM).</li>
<li>"conc" for particle concentration potential.</li>
<li>"pp" for particle pore pressure in <a href="#units">stress units</a>.</li></ul>
</li>

<li><code>Intensity "angles",(imin),(imax),(angleMin),(angleMax)</code><br>
When the first parameter for an Intensity command is "angles", its meaning changes to define a mapping from pixel gray scale values in a <a href="#bmpregionmpm">BMPRegion</a> command's <code>(anglesPath)</code> file to angle by
linearly interpolating a line through <code>(imin,angleMin)</code> and <code>(imax,angleMax)</code>. If more than one <code>(anglesPath)</code> file is used, you can have a corresponding number of <code>Intensity</code> commands to set angle mapping for each file. If fewer <code>Intensity</code> commands are used then <code>(anglesPath)</code> files, the extra files will use the mapping of the last <tt>Intensity</tt> command.</li>

<li><a name="origbmpmpm"></a><code>Origin (xO),(yO),&lt;(zO)&gt;,&lt;(flip)&gt;</code><br>
Set origin within the mesh (in <a href="#units">length units</a>) for mapping the origin of the image in a <a href="#bmpregionmpm">BMPRegion</a> command to
the grid. The optional <code>(flip)</code> can be "yes" to flip image along its y axis. The optional (z0) is for 3D MPM. Images are always mapped in the x-y plane, but by combining images at different z values, you can create a 3D object from a stack of images, such as X-ray CT data.</li>
</ul>

<p>|<a href="#cindex">Documentation Index</a>|</p>

<h2><a name="feamesh"></a>Defining the FEA Mesh</h2>

<p>These commands are used to define the FEA Mesh by creating key points, connecting them in paths, and linking paths to mesh areas:</p>

<ul>
<li><a name="keypoint"></a><code>Keypoint (id),(x),(y),&lt;(type)&gt;</code><br>
Define a key point used in defining <a href="#path">Paths</a>. <code>(id)</code> is key point ID, <code>(x)</code> and <code>(y)</code> are x and y 
coordinates (or r and z if axisymmetric) (in <a href="#units">length units</a>). The optional <code>(type)</code> can be &quot;polar&quot; to
change <code>(x)</code> and <code>(y)</code> to be R and &theta; to define key point using polar coordinates relative
to current <a href="#origin">origin</a>.</li>

<li><code>Keypoints  (id1),(id2),...</code><br>
Add multiple (and previously) defined key points to a <a href="#path">Path</a> by their key point ID.</li>

<li><a name="path"></a><code>Path (id),(numints),&lt;(ratio)&gt;<br>
&nbsp;&nbsp;(list and/or define key points along the path)<br>
EndPath</code><br>
Define a path used in defining <a href="#area">Areas</a>. <code>(id)</code> is the ID for the path. <code>(numints)</code> is the number of intervals along the path when used in a mesh. The optional <code>(ratio)</code> defines the ratio of the first element size to the last element size (default is 1). Alternatively, <code>(ratio)</code> can be negative to specify the absolute size of the first element (in <a href="#units">length units</a>) to be |<code>(ratio)</code>|.The commands within the path block should list and/or define two or three key points for the path (two points for a line or three points for a curve).</li>

<li><code>Paths (id1),(id2),...</code><br>
Add multiple defined paths to an <a href="#area">Area</a> by their path ID</li>

<li><a name="area"></a><code>Area (mat),(thick),&lt;(angle)&gt;<br>
&nbsp;&nbsp;(list and/or define <a href="#path">paths</a> and <a href="#keypoint">key points</a>)<br>
EndArea</code><br>
Define an area for mesh generation where <code>(mat)</code> is a defined <a href="#material">material ID</a>,
<code>(thick)</code> is thickness (in <a href="#units">length units</a>) (ignored in axisymmetric FEA, but still required), and
<code>(angle)</code> is an angle (for anisotropic materials) (it can be a <a href="#function">user-defined function</a>). The commands in the area block should define four paths (to enclose 2D area) or
two paths (for a 1D interface). Material ID can be &quot;_NONE_&quot; when the
elements will be filled later by <a href="feashapes">shape and image commands</a>.</li>

<li><code>Element (type)</code><br>
Define type of element to use in subsequent <a href="#area">Area</a> commands. <code>(type)</code> can be &quot;3 Node Triangle&quot; (or 1), &quot;4 Node Quadrilateral&quot; (or 2), &quot;8 Node Quadrilateral&quot; (or 3), 6 Node Triangle&quot; (or 4), &quot;4 Node Interface&quot; (or 5), 6 Node Interface&quot; (or 6), or &quot;9 Node Lagrange&quot; (or 8). The default (before any Element command) is &quot;8 Node Quadrilateral&quot;.</li>

<li><code>FlipTriangles &lt;(flip)&gt;</code><br>
Select the direction of triangular elements in meshes that use those elements where <code>(flip)</code> is &quot;Yes&quot; or &quot;No&quot; to flip; the argument can be omitted to toggle current setting</li>

<li><a name="origin"></a><code>Origin (xOorId),&lt;(yO)&gt;</code><br>
Define coordinate system origin (in <a href="#units">length units</a>) for entry of <a href="#keypoint">key points</a> using polar coordinates.
If only <code>(xOorId)</code> is given, it is key point ID for location of the new origin; if <code>(xOorId)</code> and <code>(yO)</code> are both given they are (x,y) coordinates of the origin. The default origin is (0,0). When origin is (xO,yO), key points entered with polar coordinates R and &theta; will be at (x,y) = (xO,yO) + R(cos &theta;,sin &theta;)</li>

<li><code>Resequence (xorId),&lt;(y)&gt;</code><br>
Turn on the option to resequence the nodes, which will minimize the bandwidth of
the problem and speed the calculations. If only <code>(xorId)</code> is given, it is a key point ID to start resequencing.
If <code>(xorId)</code> and <code>(y)</code> are both given, the resequencing will start at the node closest to those x and y coordinates (in <a href="#units">length units</a>).</li>

</ul>

<h3><a href="feashapes"></a>FEA Mesh Using Shapes and Images</h3>

<p>A advanced method for creating FEA meshes is to define them from images and shapes. The process is to first create a mesh using <a href="#area">Area commands</a> but for those sections to be filled by shapes and images, set the material ID to "_NONE_". After that mesh is done, fill the mesh with the following shape and images commands. These commands will assign material types to the element. Any element not assigned to be a material will be removed from the mesh.</p>

<ul>

<li><a name="regionfea"></a><code>Region (mat),(thick),&lt;(angle)&gt;<br>
&nbsp;&nbsp;(one or more <a href="#shape2D">2D shape commands</a>)<br>
EndRegion</code><br>
Define a region for assigning material types to elements within the union of the subordinate <a href="#shape2D">shape commands</a> whose
material ID was set to &quot;_NONE&quot;. <code>(mat)</code> is a defined <a href="#material">material ID</a>,
<code>(thick)</code> is thickness (in <a href="#units">length units</a>) (ignored in axisymmetric FEA, but still required),
and <code>(angle)</code> is an angle (for anisotropic materials)
(it can be a <a href="#function">user-defined function</a>).</li>

<li><a name="holefea"></a><code>Hole<br>
&nbsp;&nbsp;(one or more <a href="#shape2D">2D shape commands</a>)<br>
EndHole</code><br>
Define a region for creating a hole that removes elements in the mesh whose material
ID was set to &quot;_NONE_&quot;. The hole is defined by the union of the subordinate <a href="#shape2D">shape commands</a>.</li>


<li><a name="bmpregionfea"></a><code>BMPRegion (path),(width),&lt;(height)&gt;,&lt;anglesPath&gt;<br>
&nbsp;&nbsp;(One <a href="#origbmpfea">Origin</a> command and <a href="#intensityfea">Intensity</a> commands)<br>
EndRegion</code><br>
Create FEA elements from an image in a BMP file with <code>(path)</code> having the path for image file name. <code>(width)</code> and <code>(height)</code> give width and height of the image (in <a href="#units">length units</a>). Either can be negative to enter <a href="#units">length units</a> per pixel instead of absolute picture size. If either one is omitted, the other one is calculated by the aspect ratio of the image in the file (to omit <code>(width)</code> or <code>(height)</code> when needed for parameter alignment, the number should be more negative than -1e8).
The optional <code>(anglesPath)</code> gives path to a second BMP file (of the same size) whose gray scale values determine the angles for elements covered by the image.</li>

<li><a name="intensityfea"></a><code>Intensity (mat),(imin),(imax),&lt;(prop,value)&gt;,...</code><br>
Map pixel gray scale values in <a href="#bmpregionfea">BMPRegion</a> in the range <code>(imin)</code> to <code>(imax)</code>
to material in <code>(mat)</code>. The optional pairs <code>(prop,value)</code> can set
initial element properties with <code>(prop)</code> options of:
<ul>
<li>"thick" for element thickness in <a href="#units">length units</a>.</li>
<li>"angle" for rotation angle of the material about the z axis in degrees.</li>
<li>"temp" for element temperature in C (or K).</li>
</ul>
</li>

<li><code>Intensity "angles",(imin),(imax),(angleMin),(angleMax)</code><br>
When the first parameter for an Intensity command is "angles", its meaning changes to define a mapping from pixel gray scale values in a <a href="#bmpregionfea">BMPRegion</a> command's <code>(anglesPath)</code> file to angle by
linearly interpolating a line through <code>(imin,angleMin)</code> and <code>(imax,angleMax)</code>.</li>

<li><a name="origbmpfea"></a><code>Origin (xO),(yO),&lt;(zO)&gt;,&lt;(flip)&gt;</code><br>
Set origin within the mesh (in <a href="#units">length units</a>) for mapping the origin of the image in a <a href="#bmpregionfea">BMPRegion</a> command to
the grid. The optional <code>(flip)</code> can be "yes" to flip image along its y axis. Although <code>(zO)</code> is ignored in FEA, you need to enter a number if you want to use the <code>(flip)</code> parameter.</li>

</ul>

<h3><a name="shape2D"></a>2D Shape Commands</h3>

<p>The following commands define 2D shapes to use for <a href="#regionfea">FEA meshes</a>, for <a href="#regionmpm">MPM particles</a>, or for <a href="#bconds">MPM boundary conditions</a>. All dimensions used <a href="#units">length units</a>)</p>

<ul>

<li><a name="rect"></a><code>Rect (xmin),(xmax),(ymin),(ymax),&lt;(arcStart)&gt;,&lt;(arcEnd)&gt;</code><br>
Define rectangle using <code>(xmin)</code>, <code>(xmax)</code>, <code>(ymin)</code>, and <code>(ymax)</code>. Optional <code>(arcStart)</code> and <code>(arcEnd)</code> limit to arc of the rectangle (ccw from start to end in degrees with 0 degrees along the x axis).</li>

<li><a name="oval"></a><code>Oval (xmin),(xmax),(ymin),(ymax),&lt;(arcStart)&gt;,&lt;(arcEnd)&gt;</code><br>
Define oval within the rectangle defined by <code>(xmin)</code>, <code>(xmax)</code>, <code>(ymin)</code>, and <code>(ymax)</code>. Optional <code>(arcStart)</code> and <code>(arcEnd)</code> limit to arc of the oval (ccw from start to end in degrees with 0 degrees along the x axis).</li>

<li><a name="polypt"></a><code>PolyPt &lt;(xpt)&gt;,&lt;(ypt)&gt;</code><br>
Define next point on a polygon shape or, if no parameters, close the current polygon shape.
All polygons are automatically closed from last point to the first point (even if one is open at the end of the MPM <a href="#regionmpm">region</a> or <a href="#holempm">hole</a> block or FEA <a href="#regionfea">region</a> or <a href="#holempm">hole</a> block).</li>

<li><a name="line"></a><code>Line (x1),(x2),(y1),(y2),&lt;(tolerance)&gt;</code><br>
Define line shape from <code>(x1,y1)</code> to <code>(x2,y2)</code>. The shape will be a rectangle with ends normal to the line through the endpoints and width of <code>(tolerance)</code> on either size of the line. If <code>&lt;(tolerance)&gt;</code> is not provided it will be set to 10% of the smallest grid cell dimension.</li>

<li><a name="arc"></a><code>Arc (xmin),(xmax),(ymin),(ymax),(arcStart),(arcEnd),&lt;(tolerance)&gt;</code><br>
Define path along the edge of an oval within the rectangle defined by <code>(xmin)</code>, <code>(xmax)</code>, <code>(ymin)</code>, and <code>(ymax)</code>. The required <code>(arcStart)</code> and <code>(arcEnd)</code> define angles of the arc ccw from start to end in degrees with 0 degrees along the x axis. The shape will include space to a distance of <code>(tolerance)</code> on either side of the path. If <code>&lt;(tolerance)&gt;</code> is not provided it will be set to 10% of the smallest grid cell dimension.</li>

<li><a name="cutcmd"></a><code>Cut (Shape_Command)</code><br>
<code>Cut Cut (Shape_Command)</code><br/>
<code>...</code><br>
Shape commands can be nested by starting that command with one or more <code>Cut</code> commands (separated by spaces). First nesting removes that shape from the parent shape, the second adds that shape back, <i>etc.</i>. For proper nesting, the number of <code>Cut</code>'s must be less than or equal to previous command plus one (<i>e.g.</i>, <code>Cut</code> can be followed by <code>Cut Cut</code> for subordinate shape, <code>Cut</code> for another shape in the same parent shape, or no <code>Cut</code>s to start a new parent shape; it cannot be followed by <code>Cut Cut Cut</code>). Also note that <a href="#shape2D">2D shapes</a> or <a href="shapes3D">3D shapes</a> can only nest with other 2D and 3D shapes, respectively.
</li>

</ul>

<h3><a name="shape3D"></a>3D Shape Commands</h3>

<p>The following commands define 2D shapes to use for <a href="#regionfea">FEA meshes</a>, for <a href="#regionmpm">MPM particles</a>, or for <a href="#bconds">MPM boundary conditions</a>. All dimensions use <a href="#units">length units</a>.</p>

<ul>

<li><a name="boxmpm"></a><code>Box (xmin),(xmax),(ymin),(ymax),(zmin),(zmax)</code><br>
Define cubical volume using <code>(xmin)</code>, <code>(xmax)</code>, <code>(ymin)</code>, <code>(ymax)</code>, <code>(zmin)</code>, and <code>(zmax)</code> for the current
<a href="#regionmpm">region</a> or <a href="#holempm">hole</a> block.</li>

<li><a name="spherempm"></a><code>Sphere (xmin),(xmax),(ymin),(ymax),(zmin),(zmax)</code><br>
Define spherical volume within the cubical volume  defined by <code>(xmin)</code>, <code>(xmax)</code>, <code>(ymin)</code>, <code>(ymax)</code>, <code>(zmin)</code>, and <code>(zmax)</code> for the current
<a href="#regionmpm">region</a> or <a href="#holempm">hole</a> block.</li>

<li><a name="cylindermpm"></a><code>Cylinder (xmin),(xmax),(ymin),(ymax),(zmin),(zmax),(axis),&lt;(radius)&gt;</code><br>
Define cylindrical volume within the cubical volume  defined by <code>(xmin)</code>, <code>(xmax)</code>, <code>(ymin)</code>, <code>(ymax)</code>, <code>(zmin)</code>, and <code>(zmax)</code> along axis <code>(axis)</code> (1, 2, 3, x, y, or z) for the current <a href="#regionmpm">region</a> or <a href="#holempm">hole</a> block. Optional <code>(radius)</code> converts to cone with relative radius (-1 to 1) at the top (if >0)
or at the bottom (if &lt; 0).</li>

<li><a name="torusmpm"></a><code>Torus (xmin),(xmax),(ymin),(ymax),(zmin),(zmax),(axis),&lt;(radius)&gt;</code><br>
Define toriodal volume within  dimensions defined by <code>(xmin)</code>, <code>(xmax)</code>, <code>(ymin)</code>, <code>(ymax)</code>, <code>(zmin)</code>, and <code>(zmax)</code> along axis <code>(axis)</code> (1, 2, 3, x, y, or z) for the current <a href="#regionmpm">region</a> or <a href="#holempm">hole</a> block. The (axis) specifies the normal direction to the plane of the torus. The bounds for the directions in the plane of the torus (e.g., x and y bounds when axis is z) define an ellipsoid (or circle if the bounds have the same separation) that runs through the center of the toroidal ring. The bounds in the direction of the axis define top and bottom for the cross-section of the toroidal ring. The cross section will be a circle with radius given by half the distance between the top and bottom. To have an elliptical cross section, you can specify optional parameter (radius) to define the radius of the cross section in the plane of the torus (while top and bottom give radius of the cross section in the axis direction).</li>

<li><a name="line3D"></a><code>Line (x1),(x2),(y1),(y2),(z1),(z2),&lt;(tolerance)&gt;</code><br>
Define line shape from <code>(x1,y1,z1)</code> to <code>(x2,y2,z2)</code>. The shape will be a cylinder with ends normal to the line, the line down the axis, and radius of <code>(tolerance)</code>. If <code>&lt;(tolerance)&gt;</code> is not provided it will be set to 10% of the smallest grid cell dimension.</li>

<li><code>PolyPt (xpt),(ypt),(zpt)</code><br>
Define next point on a polyhedron shape. After defining 4 to 8 points, the type of polyhedron <i>must</i> be terminated with the following <code>PolyPt</code> using text arguments,</li>

<li><code>PolyPt (style),(details)</code><br>
The polyhedron defined by the previous block of points is determined by a <code>PolyPt</code> with these arguments. <code>(style)</code> of "pyramid" is a pyramid shape for which the first point is the apex of the pyramid and the remaining 3 or 4 points define a triangular or quadrilateral base. <code>(style)</code> of "trivectors" or "tripts" defines a triclinic shape from 4 points. The first point is one corner or origin of the shape. For "trivectors", the remaining points are vectors along the three edges emanating from the shape's origin. For "tripts", the remaining points are end points of those vectors. <code>(style)</code> of "box" defines an arbitrarily shaped 8-corner box from 8 specified points. Points 1,2,3,4 define bottom face of box and 5,6,7,8 define the top face (ccw around each face with point 5 above point 1). The points can be specified in any order as determined by the <code>(details)</code> parameter as list of 8 integers each within the range of 1 to 8 (<i>e.g.</i>, "13572486"). Some graphics illustrating these shapes is on-line <a href="http://osupdocs.forestry.oregonstate.edu/index.php/3D_MPM_Shape_Commands#Polyhedron">here</a>.</li>

<li><code>Cut (Shape_Command)</code><br>
<code>Cut Cut (Shape_Command)</code><br/>
<code>...</code><br>
See <a href="#cutcmd">Cut</a> command above, which can also nes 3D shapes..
</li>

</ul>

<p>|<a href="#cindex">Documentation Index</a>|</p>

<h2><a name="cracks"></a>Defining Explicit Cracks in MPM</h2>

<p>Cracks in MPM calculations are implemented using the CRAMP algorithm first described by Nairn (developer of this software) and coworkers.</p>

<h3>Defining Crack Geometry</h3>

<p>These commands define explicit crack paths (all dimensions use <a href="#units">length units</a>):</p>

<ul>
<li><code>NewCrack (x),(y),&lt;(matoption)&gt;,&lt;(lawid)&gt;,&lt;(tract)&gt;</code><br>
Start new crack at <code>(x,y)</code>. <code>(matoption)</code> can be crack tip material, &quot;fixed&quot; (to be fixed crack),
&quot;exterior&quot; (for crack
that extends beyond object), or &quot;free&quot; (no material). <code>(law)</code> can set a custom <a href="materials.html#contactlaws">contact law</a> for this crack (as explained in the <a href="#contactcracks">ContactCracks command</a>) or can be
&quot;traction&quot;. If <code>(lawid)</code> is &quot;traction&quot;, <code>(tract)</code> must be a traction law material. (Note: a deprecated use of the <code>(lawid)</code> parameter was to set frictional contact by setting <code>(lawid)</code> to options allowed for the <a href="#frict">Friction Command</a>).</li>

<li><code>GrowCrackLine (x),(y),(segs),&lt;(mat)&gt;,&lt;(tract)&gt;</code><br>
Extend current crack to <code>(x,y)</code> using <code>(segs)</code> crack segments. <code>(mat)</code> can be crack tip material, &quot;exterior&quot; (for crack that extends beyond object), or invalid ID (no material). <code>(tract)</code> is a traction law material to use in wake of crack propagation from this crack tip.</li>

<li><code>GrowCrackArc (x1),(y1),(x2),(y2),(segs),(start),(and),&lt;(mat)&gt;,&lt;(tract)&gt;</code><br>
Grow crack along arc along the elipse bounded by <code>(x1,y1)</code> and <code>(x2,y2)</code> from angle <code>(start)</code> to <code>(end)</code> (in degrees) using <code>(segs)</code> segments. The arc is drawn in the counter-clockwise direction and the positive x axis is angle of zero degrees.
<code>(mat)</code> can be crack tip material, &quot;exterior&quot; (for crack that extends beyond object), or invalid ID (no material). <code>(tract)</code> is a traction law material to use in wake of crack propagation from this crack tip.</li>

<li><code>GrowCrack (x),(y),&lt;(mat)&gt;,&lt;(tract)&gt;</code><br>
Extend current crack to <code>(x,y)</code> using 1 crack segment. <code>(mat)</code> can be crack tip material, &quot;exterior&quot; (for crack that extends beyond object), or invalid ID (no material). <code>(tract)</code> is a traction law material to use in wake of crack propagation from this crack tip.</li>

<li><code>CrackThickness (thick)</code><br>
Sets crack thickness to <code>(thick)</code>; only used or needed when crack has traction laws or crack tips release their energy into heat.</li>

</ul>

<h3><a name="csettings"></a>Crack Settings</h3>

<p>This commands define default crack modeling settings (although each crack can change them to have cracks with different settings:</p>

<ul>
<li><a name="contactcracks"></a><code>ContactCracks (lawid)</code><br>
Set default crack <a href="materials.html#contactlaws">contact law</a> using the law's ID in <code>(lawid)</code>. Any specific crack can use a different contact law by using the <code>(lawid)</code> argument in the <a href="#cracks">NewCrack command</a>.
</li>

<li><a name="propagate"></a><code>Propagate (criterion),&lt;(direction)&gt;,&lt;(tract)&gt;</code><br>
Activate and select crack propagation method. The (<code>criterion)</code> selects the crack propagation failure criterion (by name or number):
<ul>
<li>"none" (or 0) - no propagation</li>
<li>"max energy release" (or 1)</li>
<li>"steady state" (or 2)</li>
<li>"energy balance" (or 3)</li>
<li>"energy density" (or 4)</li>
<li>"elliptical" (or 5)</li>
<li>"max ctod"</li>
<li>"critical err"</li>
</ul>
The <code>(direction)</code> select the crack growth direction (by name or number)
<ul>
<li>"default" (or 0) - use default direction for each criterion</li>
<li>"self similar" (or 1)</li>
<li>"cod normal" (or 2)</li>
<li>"cod hoop" (or 3)</li>
<li>"initial" (or 4)</li>
</ul>
The optional <code>(tract)</code> (for a material ID) is to leave traction law in wake of propagation.</li>

<li><code>AltPropagate (criterion),&lt;(direction)&gt;,&lt;(tract)&gt;</code><br>
Set a second rule for crack propagation with competing fracture modes. The parameters are the
save as for the <a href="#propagate">Propagate command</a> below.</li>

<li><code>PropagateLength (length)</code><br>
Determines the amount of crack growth each time a crack propagates, where <code>(length)</code> is relative to cell dimensions. The default is 0.5.</li>

<li><code>JContour (size),&lt;(terms)&gt;,&lt;(usegrid)&gt;</code><br>
Used to set size of J integral contour (<code>(size)</code> in cells for semi length of enclosing box),
whether J integral uses one or two terms (<code>(terms)</code> = 1 or 2), and whether kinetic and work energy
are found by extrapolating energies (<code>(usegrid)</code>="no") or by extrapolating velocity, stress, and strain
and then calculating energies (if <code>(usegrid)</code>="yes"; "no" is recommended unless you notice kinetic energy artifacts and are in the small-strain, linear elastic limit).</li>

<li><code>MovePlane (how),&lt;(prevent)&gt;</code><br>
Used to set how crack plane particles move where <code>(how)</code> is "avg" or "cm" to move to average of crack surfaces or to move in the center of mass velocity field, and <code>(prevent)</code> is "yes" or "no" to prevent crack surfaces from crossing the main crack plane.</li>

<li><a name="CPCommand"></a><code>ContactPositionCracks (con)</code><br>
Determines the method used for detecting crack surface contact. The command use and its <code>(con)</code> argument have three options:
<ol>
<li><code>(con)</code> &gt; 0 means that distance (entered relative to grid element dimensions) is subtracted from extrapolated particle positions to calculate crack surface separation. Calculations and simulations show the 0.8 is a good value for GIMP or CPDI shape functions with two particle per cell axis (other settings might need a different value).</li>
<li><code>(con)</code> &lt; 0 means to use an advanced calculation to adjust extrapolated positions to detect separation (unpublished results). The absolute value of the argument is used as power for one term in the adjustment expression. Calculations and simulations show the -0.58 a good value for GIMP or CPDI shape functions with two particle per cell axis (other settings might need a different value or might new recoding for form of the power-law expressions).</li>
<li>No <code>ContactPositionCracks</code> command: If a simulation has no <code>ContactPositionCracks</code> command, the crack surface separation is determined by extrapolating particle displacements rather than position. The displacements are used uncorrected in contact calculations.</li>
</ol>
The default condition is no <code>ContactPositionCracks</code> command and it is the preferred method when all cracks start out in contact. A separate <a href="#CPMatCommand">ContactPosition</a> commands determines method used for detecting <a href="#mmmode">material contact</a>.</li>

</ul>

<p>When modeling cracks, you can use the <a href="#toarchive">ToArchive command</a> to select various crack parameters for output in the archive files. The archiving options for crack parameters are jintegral, stress, and energybalance.</p>

<p>A few <a href="#deprecate">deprecated commmands</a> can set crack options, but should be replaced now by the above commands.</p>

<p>|<a href="#cindex">Documentation Index</a>|</p>


<h2><a name="feacracks"></a>Cracks in FEA Calculations</h2>

<p>Cracks in FEA calculations are set up by configuring the mesh to include a crack. A crack can be internal to the mesh or, for symmetric loading, can be on an edge of the mesh and defined with the help of boundary conditions. These two crack geometries are illustrated here:</p>
<center>
<img src = "ccfull.jpg" width = "190" height = "192" alt = "" align="top">
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<img src = "cchalf.jpg" width = "201" height = "228" alt = "" align="top">
</center>
<p>The crack plane edges must be collinear and of equal length (&Delta;a). When a calculation with cracks is done, the Crack Closure... command (in NairnFEAMPM) can be used to calculate crack tip energy release rate.</p>
<p>The one command to alter crack tip geometry is
</p>
<ul>
<li><code>CrackTip (xtip),&lt;(ytip)&gt;</code><br>
Create quarter-point elements at the crack tip. If only <code>(xtip)</code> is given, it is an ID for the key point at the crack tip. 
If two arguments are given, the node closet to <code>(xtip,ytip)</code> (in <a href="#units">length units</a>) is the crack tip.</li>
</ul>

<p>|<a href="#cindex">Documentation Index</a>|</p>

<h2><a name="mmmode"></a>Multimaterial MPM Calculations</h2>

<p>NairnMPM can use multimaterial mode where each material has its own velocity field
and intersections between materials on nodes are resolved using various contact
mechanics models. The key commands to use this mode are:</p>

<ul>
<li><code>MultimaterialMode 0.0,1,&lt;(norm)&gt;,&lt;(rigidBiasOrAzimuth)&gt;,&lt;(polar)&gt;</code><br>
Sets to use multimaterial modes and sets some options.
The first two parameters are no longer used, but should specify previous default values (0.0 and 1) for parameter alignment. <code>(norm)</code> determines the method used to find surface normals during
contact calculations, with options:
<ul>
<li>&quot;maxgrad&quot; (or 0)</li>
<li>&quot;maxvol&quot; (or 1)</li>
<li>&quot;avggrad&quot; (or 2) (default)</li>
<li>&quot;owngrad&quot; (or 3)</li>
<li>&quot;specify&quot; (or 4)</li>
<li>&quot;linreg&quot; (or 5)</li>
<li>&quot;logreg&quot; (or 4)</li>
</ul>
When <code>(norm)</code> is "maxgrad," "avggrad," "linreg," or "logreg," the <code>(rigidBiasOrAzimuth)</code> parameter sets a bias factor to use rigid normal over nonrigid material normal (default 1). When <code>(norm)</code> is "specify", the <code>(rigidBiasOrAzimuth)</code> and <code>(polar)</code> parameters set the azimuth (&phi;) and polar (&theta;) angles for the normal vector, which is given by (cos &phi; sin &theta;, sin &phi; sin &theta;, cos &theta;). For 2D calculations, the <code>(polar)</code> setting is ignored (and automatically set to 90 degrees). The normal should point from the lower-numbered material to the higher-numbered material. For contact with rigid materials, the normal should point from the non-rigid material to the rigid material.</li>

<li><a name="CPMatCommand"></a><code>ContactPosition (con)</code><br>
Determines method used to evaluate material separation. See <a href="#CPCommand"><code>ContactPositionCracks</code></a> command for the options, but this command applies those options to material contact instead of crack contact. Unless materials start out in contact, the preferred option for material contact is to use a <code>ContactPosition</code> command. A simulation can use one of both of these commands to allow crack contact and material contact to use different methods for finding separation. A common situtation in multimaterial mode with cracks is to use <code>ContactPosition</code> command but omit the <code>ContactPositionCracks</code> command. For compatibility with old code that had only one <code>ContactPosition</code> option, simulations in single material mode that use a <code>ContactPosition</code> will apply that command to crack contact.  </li>

<li><a name="contactmm"></a><code>ContactMM (frict)</code><br>
Set default multimaterial mode <a href="materials.html#contactlaws">contact law</a> by material ID in <code>(lawID)</code>.</li>

<li><a name="contactprop"></a><code>Contact (lawid),(mat)</code><br>
When this command is used within a <a href="#material">material</a> definition, it can set custom
material-material <a href="materials.html#contactlaws">contact law</a> by that law's ID in <code>(lawid)</code> and where <code>(mat)</code> is material ID for the other material. Otherwise materials use the default
settings from a <a href="#contactmm">ContactMM</a> command.</li>

<li><code>shareMatField (matID)</code><br>
When this command is used within a <a href="#material">material</a> definition, it allows two or more
materials to <a href="materials.html#cmn4">share the same velocity field</a>.</li>

</ul>

<p>A few <a href="#deprecate">deprecated commmands</a> can set multimaterial mode options, but should be replaced now by the above commands.</p>


<p>|<a href="#cindex">Documentation Index</a>|</p>


<h2><a name="thermal"></a>MPM Thermal Calculations</h2>

<p>These commands are used to do thermal stress and thermal conductivity calculations</p>

<ul>
<li><code>Conduction (conduct),&lt;(option)&gt;,...</code><br>
Turn on thermal conductivity calculations and define heat source options with (conduction) of "yes" or "no". The optional parameters active various thermal calculation options:
<ul>
<li>&quot;Adiabatic&quot;</li>
<li>&quot;Isothermal&quot;</li>
<li>"Crack Tips" - crack growth causes a heat source</li>
<li>"Friction" - work of material friction converted to heat</li>
<li>"Crack Friction" - work of crack friction converted to heat</li>
</ul>
</li>

<li><code>ThermalRamp</code><br>
A <a href="#CustomThermalRamp">ThermalRamp custom task</a> can be used to ramp temperature difference applied to particles.</li>

<li><code>StressFreeTemp (temp)</code><br>
Set the stress free temperature to (temp) (in K).</li>

</ul>

<p>When doing thermal calculations, you must use the <a href="#material">material</a> command methods to define material properties needed for thermal calculations (coefficient of thermal expansion, thermal conductivity, heat capacity). You can apply <a href="#bconds">temperature and heat flux</a> boundary conditions. You can use <a href="#regionmpm">Region</a> or <a href="#bmpregionmpm">BMPRegion</a> commands to set initial particle temperature. You can use the <a href="#toarchive">ToArchive</a> and <a href="#globalarchive">GlobalArchive</a> commands to select various thermal parameters for output in the archive files, such as concentration, temperature, and heat energy.</p>

<p>|<a href="#cindex">Documentation Index</a>|</p>

<h2><a name="thermalfea"></a>FEA Thermal Calculations</h2>

<p>These commands are used to do thermal stress calculations</p>

<ul>
<li><code>StressFreeTemp (temp)</code><br>
Set the stress free temperature to <code>(temp)</code> (in K); the default is zero.</li>

<li><code>Temperature (temp)</code><br>
Apply temperature <code>(temp)</code> to all nodes (in K). Enter a <a href="#function">user defined function</a>
of nodal position (x and y). It is only the difference between temperature and stress free temperature that matters in FEA calculations.
</li>

</ul>

<p>In addition, you must use the <a href="#material">material</a> command methods to define material properties
needed for thermal calculations (coefficient of thermal expansion).</p>

<p>|<a href="#cindex">Documentation Index</a>|</p>

<h2><a name="conc"></a>Diffusion Calculations</h2>

<p>The command to activate diffusion calculations is (MPM only):</p>

<ul>

<li><code>Diffusion (diff),&lt;(res)&gt;</code><br>
To turn on diffusion calculations. <code>(diff)</code> is "yes" or "no" to activate diffusion. <code>(res)</code> can specify a reference concentration between 0 and 1 (default is 0).</li>

</ul>

<p>When doing concentration calculations, you must use the <a href="#material">material</a> command methods to define material properties needed for diffusions calculations (coefficient of moisture expansion, diffusion constant, saturation concentration). You can apply <a href="#bconds">concentration and concentration flux</a> boundary conditions. You can use <a href="#regionmpm">Region</a> or <a href="#bmpregionmpm">BMPRegion</a> commands to set initial particle concentration. You can use the <a href="#toarchive">ToArchive</a> and <a href="#globalarchive">GlobalArchive</a> commands to add concentration concentration gradients to archive files.</p>

<p>|<a href="#cindex">Documentation Index</a>|</p>

<h2><a name="poro"></a>Poroelasticity Calculations</h2>

<p>The command to activate poroelasticity calculations is (MPM only):</p>

<ul>

<li><code>Poroelasticity (poro),&lt;(res)&gt;,&lt;(visc)&gt;</code><br>
To turn on poroelasticity calculations. <code>(poro)</code> is "yes" or "no" to activate poroelasticity. <code>(res)</code> can specify a reference pore pressure in <a href="#units">pressure units</a> (default is 0). <code>(visc)</code> viscosity of the fluid in the pores in cP for Legacy units but in <a href="#units">viscosity units</a> for consistent units (default is 1 <a href="#units">viscosity unit</a>).</li>

</ul>

<p>When doing poroelasticity calculations, you must use the <a href="#material">material</a> command methods to define material properties needed for poroelasticity calculations (undrained bulk modulus, Biot coefficient, and Darcy's law permittivity). You can apply <a href="#bconds">pore pressure and pore pressure flux</a> boundary conditions. You can use <a href="#regionmpm">Region</a> or <a href="#bmpregionmpm">BMPRegion</a> commands to set initial particle pore pressure. You can use the <a href="#toarchive">ToArchive</a> and <a href="#globalarchive">GlobalArchive</a> commands to add pore pressure and pore pressure gradient to archive files.</p>

<p>|<a href="#cindex">Documentation Index</a>|</p>

<h2><a name="bconds"></a>Applying MPM Boundary Conditions</h2>

<h3>Grid-Based Boundary Conditions</h3>

<p>Grid based boundary conditions are used to set velocity, temperature, and/or concentration on the grid:</p>

<ul>
<li><code>GridBC<br>
&nbsp;&nbsp;(one <a href="#shape2D">2D</a> or <a href="#shape2D">3D</a> shape)<br>
&nbsp;&nbsp;(grid condition commands)<br>
EndMoveLine</code><br>
Apply <a href="#velbc">velocity</a>, <a href="#tempbc">temperature</a>, <a href="concbc">concentration</a>, or <a href="#ppbc">porepressure</a> conditions to all nodes within the provided shape (which can be a <a href="#cutcmd">nested shape</a>).</li>

<li><a name="velbc"></a><code>Velocity (dir),(style),&lt;(value)&gt;,&lt;(time)&gt;,&lt;(skew)&gt;,&lt;(skew2)&gt;</code><br>
Apply velocity conditions to currently selected nodes in the (dir) direction (x, t, z, skewxy, skewxz,
skewyz, skewxyz, or skewrz). <code>(style)</code> is style with <code>(value)</code> (in <a href="#units">velocity units</a>) and <code>(time)</code> as optional arguments to set the <a href="#bcstyle">style</a> for the boundary condition. If <code>(dir)</code> is skewxy, skewxz, skewyz, or skewrz, <code>(skew)</code> is skew angle rotated clockwise from the first axis in the skew pair. If <code>(skew2)</code> is skewxyz, <code>(skew2)</code>is second angle such that <code>(skew)</code> and <code>(skew2)</code> are polar and azimuthal angles for the 3D skew direction.</li>

<li><code>Velocity (dir),"gradient",(velFxn),0,(depth),&lt;(gradFxn)&gt;,&lt;(dispFxn)&gt;</code><br>
A <code>Velocity</code> command with "gradient" in the second and "0" in fourth parameter (for alignment) sets a moving wall that is perpendicular to the <code>x</code>, <code>y</code>, or <code>z</code> axis (in the (dir) parameter). <code>(velFxn)</code> is a <a href="#function">user-defined function</a> of time (<code>t</code> in <a href="#units">alt time units</a>) and initial nodal point position (in <a href="#units">length units</a>) that gives the wall velocity in <a href="#units">velocity units</a>.<br>
&nbsp;&nbsp;&nbsp;&nbsp;<code>(depth)</code> has two functions. The sign of <code>(depth)</code> determines if the wall is at minimum edge (if minus) or positive edge (if plus) of material points on the selected axis. The magnitude of <code>(depth)</code> determines how many nodes will get velocity boundary conditions. A moving wall boundary condition applies velocity to all active nodes outside the wall and all nodes inside the wall less than or equal to <code>|(depth)|</code> cells from the wall.<br>
&nbsp;&nbsp;&nbsp;&nbsp;<code>(gradFxn)</code> is a <a href="#function">user-defined function</a> of time (<code>t</code> in <a href="#units">alt time units</a>) and current wall position (in <a href="#units">length units</a>) that evaluates to a velocity gradient in moving direction in <a href="#units">(velocity units)/(length units)</a>. If the parameter is omitted, the velocity gradient is assumed to be zero.
If <code>(gradFxn)="mirror"</code>, the gradient will be calculated from velocities extrapolated to the grid by interpolating from two active nodes near <code>(depth)</code> grid cells from the wall to the current wall position and velocity. A "mirror" gradient can improve boundary conditions in problems where you do not know the velocity gradient, but you do know it should not be zero.<br>
&nbsp;&nbsp;&nbsp;&nbsp;<code>(dispFxn)</code> is a <a href="#function">user-defined function</a> of time (<code>t</code> in <a href="#units">alt time units</a>) and initial nodal point position (in <a href="#units">length units</a>). The function should evaluate to the current wall displacement from its initial position in <a href="#units">length units</a>.If omitted, the displacement is zero or the wall is fixed on the initial node.</li>

<li><a name="tempbc"></a><code>Temperature (style),&lt;(value)&gt;,&lt;(time)&gt;</code><br>
Apply temperature boundary conditions to selected nodes. <code>(style)</code> is style with <code>(value)</code> (in K) and <code>(time)</code> as optional arguments to set the <a href="#bcstyle">style</a> for the boundary condition.
</li>

<li><a name="concbc"></a><code>Concentration (style),&lt;(value)&gt;,&lt;(time)&gt;</code><br>
Apply concentration conditions to selected nodes. <code>(style)</code> is style with <code>(value)</code> (in concentration potential) and <code>(time)</code> as optional arguments to set the <a href="#bcstyle">style</a> for the boundary condition.
</li>

<li><a name="ppbc"></a><code>PorePressure (style),&lt;(value)&gt;,&lt;(time)&gt;</code><br>
Apply pore pressure conditions to selected nodes. <code>(style)</code> is style with <code>(value)</code> (in <a href="#units">stress units</a>) and <code>(time)</code> as optional arguments to set the <a href="#bcstyle">style</a> for the boundary condition.
</li>

<li><code>BoundaryID &lt;(id)&gt;</code><br>
Set ID for subsequent velocity boundary condition for use when global archiving reaction forces. The <code>(id)</code> should be negative. If omitted it is set to 0 (which means ID is not set). These IDs are needed when archiving <a href="#globalarchive">reaction forces</a>. If you need to get reaction force on boundary conditions created by <a href="#gridhoriz">symmetry planes</a> or by rigid particles when <a href="#mhother"><code>ExtrapolateRigid</code> command</a> is used, those conditions will automatically have the following boundary IDs:
<ul>
<li>-10: plane a minimum x edge</li>
<li>-11: plane a maximum x edge</li>
<li>-20: plane a minimum x edge</li>
<li>-21: plane a maximum x edge</li>
<li>-30: plane a minimum x edge</li>
<li>-31: plane a maximum x edge</li>
<li>-40: boundary condition created by extrapolating rigid particles</li>
</ul>
</li>

</ul>

<h3>Particle-Based Boundary Conditions</h3>

<p>These commands are used to apply force, traction, heat flux, or concentration flux boundary conditions directly on the particles:</p>

<ul>

<li><code>ParticleBC<br>
&nbsp;&nbsp;(one <a href="#shape2D">2D</a> or <a href="#shape2D">3D</a> shape)<br>
&nbsp;&nbsp;(particle condition commands)<br>
ParticleBC</code><br>
Apply <a href="#force">force</a>, <a href="#traction">traction</a>, <a href="#hflux">heat</a>, <a href="#cflux">concentration</a>, or <a href="#pflux">porepressure</a> flux conditions, or <a href="#damage">initial damage state</a> to all particles within the one shape (which can be a <a href="#cutcmd">nested shape</a>).</li>

<li><a name="force"></a><code>Load (dir),(style),(value),&lt;(time)&gt;</code><br>
Apply force to selected particles in direction (dir) (x, y, z (or 1, 2, or 3 or R or Z if axisymmetric). <code>(style)</code> is style with <code>(value)</code> (in <a href="#units">force units</a>, but see <a href="loadtype">LoadType command</a>) and <code>(time)</code> as optional arguments to set the <a href="#bcstyle">style</a> for the boundary condition.</li>

<li><a name="traction"></a><code>Traction (dir),(face),(style),(value),&lt;(time)&gt;</code><br>
Apply traction to selected particles in direction <code>(dir)</code> (x, y, z (or 1, 2, or 3 or R or Z if axisymmetric) on face <code>(face)</code> (1 to 6). <code>(dir)</code> can additionally be "normal" or "shear" (or 11 or 12); to have stresses normal or shear to the particle domain surface. Normal tractions are positive to apply tensile stress to the domain; shear tractions are positive when they rotate the particle domain in the counter-clockwise direction (shear for 2D only). In 2D, face is 1 to 4 for bottom, right, top, and left faces. In 3D, 1 to 4 are force faces in x-y plane, 5 and 6 are for bottom and top faces in z plane. <code>(style)</code> is style with <code>(value)</code> (in <a href="#units">pressure units</a>) and <code>(time)</code> as optional arguments to set the <a href="#bcstyle">style</a> for the boundary condition.</li>

<li><code>ExactTractions &lt;(option)&gt;</code><br>
</li>This command (need not be in ParticleBC block) activates a mode where <a href="#traction">traction loads</a> will be found by exactly integrating shape functions over the deformed particle edge. The parameter <code>(option)</code> is "yes" to activate the mode or anything else to not activate the mode. If <code>(option)</code> is omitted, it is assumed to be "yes". This feature is only allowed for <a href="#mpmmethod">uGIMP or lCPDI shape functions</a> and 2D simulations.</li>

<li><a name="loadtype"></a><code>LoadType (type)</code><br>
Specify loads in current shape command as "net" loads or "perParticle" loads (default is "perParticle"). When set to net, the load specified by the <a href="#force">Load command</a> is spread out over all particles in that shape.</li>

<li><a name="hflux"></a><code>HeatFlux (mode),(face),(style),(value),&lt;(time)&gt;</code><br>
Apply heat flux to selected particles on face <code>(face)</code> (see <a href="#traction">Traction command</a> for meaning of (face) parameter). For <code>(mode)</code>=external, <code>(style)</code> is style with <code>(value)</code> (in <a href="#units">heat flux units</a>) and <code>(time)</code> as optional arguments to set the <a href="#bcstyle">style</a> for the boundary condition. For <code>(mode)</code>=coupled, <code>(style)</code> must be "function", <code>(value)</code> is a <a href="#function">user-defined function</a> where <code>t</code> is particle temperature, and if <code>(time)</code> is supplied the coupled condition is applied only after the entered time (in <a href="#units">alt time units</a>).</li>

<li><a name="cflux"></a><code>ConcentrationFlux (mode),(face),(style),(value),&lt;(time)&gt;</code><br>
Apply concentration flux to selected particles on face <code>(face)</code> (see <a href="#traction">Traction command</a> for meaning of (face) parameter). For <code>(mode)</code>=external, <code>(style)</code> is style with <code>(value)</code> (in concentration potential) and <code>(time)</code> as optional arguments to set the <a href="#bcstyle">style</a> for the boundary condition. For <code>(mode)</code>=coupled, <code>(style)</code> must be "function", <code>(value)</code> is a <a href="#function">user-defined function</a> where <code>t</code> is difference between particle concentration (0 to 1) and a reservoir concentration, and <code>(time)</code> is the reservoir concentration (0 to 1).</li>

<li><a name="ppflux"></a><code>PorePressureFlux (mode),(face),(style),(value),&lt;(time)&gt;</code><br>
Apply pore fluid volume fraction flux to selected particles on face <code>(face)</code> (see <a href="#traction">Traction command</a> for meaning of (face) parameter). For <code>(mode)</code>=external, <code>(style)</code> is style with <code>(value)</code> (in pore fluid volume fraction/(<a href="#units">(length units)^2</a>-sec) and <code>(time)</code> as optional arguments to set the <a href="#bcstyle">style</a> for the boundary condition. For <code>(mode)</code>=coupled, <code>(style)</code> must be "function", <code>(value)</code> is a <a href="#function">user-defined function</a> where <code>t</code> is difference between particle pore pressure and a reservoir pore pressure, and <code>(time)</code> is the reservoir pore pressure (both in <a href="#units">pressure units</a>).</li>

<li><a name="damage"></a><code>Damage (nx),(ny),&lt;(nz)&gt;,&lt;(dn)&gt;,&lt;(dxy)&gt;,&lt;(dxz)&gt;,&lt;(mode)&gt;
</code><br>
Set initial particle damage where <code>(nx, ny, nz)</code> is normal vector for the damage plane, <code>(dn, dxy, dxz)</code> defines the three damage parameters (default 1), and <code>(mode)</code> is damage mode or value for first damage history variable (default 1). In 2D calculations, <code>(nz)</code> and <code>(dxz)</code> are ignored, but are needed for parameter alignment.</li>
</ul>

</ul>

<h3><a name="bcstyle"></a>MPM Boundary Condition Styles</h3>

<p>The following styles (by name or number) can use used for MPM boundary conditions. The boundary condition command provides <code>(value)</code> and <code>(time)</code> parameters where <code>(value)</code> is in units of the boundary condition (unless changed) and <code>(time)</code> is in <a href="#units">alt time units</a>:</p>

<ul>
<li>"constant" (or 1) - Set condition to <code>(value)</code> starting at <code>(time)</code> .</li>
<li>"linear" (or 1) - Set condition to <code>(value)*[t-(time)]</code> where <code>t</code> is current time. The condition starts at <code>(time)</code> and <code>(value)</code> should be condition units per <a href="#units">alt time unit</a>.</li>
<li>"sine" (or 3) - Set condition to <code>(value)*sin[t*(time)]</code> where <code>t</code> is current time and <code>(time)</code> is in <a href="#units">1/alt time units</a>.</li>
<li>"cosine" (or 4) - Set condition to <code>(value)*cos[t*(time)]</code> where <code>t</code> is current time and <code>(time)</code> is in <a href="#units">1/alt time units</a>.</li>
<li>"silent" (or 5) - Set an absorbing boundary condition. This style can only be used for <a href="#force">load</a>, <a href="#hflux">heat</a>, or <a href="#cflux">concentration</a> flux conditions. For loads, it is meant to absorb stress waves as if simulating a large object; the edge must be normal to x, y, or z direction and the material must be isotropic. For heat and concentration flux conditions, it attempts to apply extrapolated flux, which may simulation flow through and out of a layer of material.</li>
<li>"function" (or 6) - Set condition to the <a href="#function">user-defined function</a> given in <code>(value)</code>, which can depend on time (<code>t</code> in <a href="#units">alt time units</a>) and/or nodal coordinates (<code>x</code>, <code>y</code>, <code>z</code>, <code>R</code>, <code>Z</code>, <code>D</code>, and <code>T</code> in <a href="#units">length units</a>). If the <code>(time)</code> parameter is used the condition starts at <code>(time)</code> and the function is evaluated at <code>[t-(time)]</code>.</li>
</ul>


<p>|<a href="#cindex">Documentation Index</a>|</p>

<h2><a name="feabcs"></a>Applying FEA Boundary Conditions</h2>

<p>These commands are used to apply boundary conditions to FEA mesh.</p>

<ul>

<li><a name="fixline"></a><code>FixLine (x1OrID),&lt;(y1)&gt;,&lt;(x2)&gt;,&lt;(y2)&gt;,&lt;(tol)&gt;<br>
&nbsp;&nbsp;(<a href="#displacement">Displacement</a>, <a href="#load">Load</a>, or <a href="#rotate">Rotate</a> commands)<br>
&nbsp;&nbsp;(<a href="#stress">Stress</a> commands when fixing a path)<br>
&nbsp;&nbsp;(optional <a href="#select">Select</a> command)<br>
EndFixLine</code><br>
Apply displacement or load conditions to nodes along a line. If only <code>(x1OrID)</code> is given, it must be a <a href="#path">path ID</a>. If more parameters are given, the conditions are applied to all nodes along the line from <code>(x1,y1)</code> and <code>(x2,y2)</code> with optional tolerance <code>(tol)</code> (all in <a href="#units">length units</a>).</li>

<li><a name="fixpoint"></a><code>FixPoint (xOrID),&lt;(y)&gt;<br>
&nbsp;&nbsp;(<a href="#displacement">Displacement</a>, <a href="#load">Load</a>, or <a href="#rotate">Rotate</a> commands)<br>
&nbsp;&nbsp;(optional <a href="#select">Select</a> command)<br>
EndFixPoint</code><br>
Apply displacement or load conditions to a single node. If only <code>(xOrID)</code> is given, it must be a <a href="#keypoint">key point ID</a> and boundary conditions are applied to that node. If <code>(y)</code> is provided, <code>(xOrID,y)</code> defines coordinates (in <a href="#units">length units</a>) for a point and the boundary conditions will be applied to the one node nearest to that point.</li>

<li><a name="displacement"></a><code>Displacement (dir),&lt;(value)&gt;</code><br>
Apply displacement conditions to nodes in current shape. <code>(dir)</code> is x or y (or 1 or 2) to
specify the direction of the applied displacement (they can R or Z for axisymmetric).
<code>(value)</code> specifies magnitude of the displacement in <a href="#units">length units</a>.
It can be specified by a number or by a <a href="#function">user-defined function</a> of nodal point position, entered as quoted text. If <code>(value)</code> is omitted, the default displacement is 0.</li>

<li><a name="load"></a><code>Load (dir),(value)</code><br>
Apply forces to nodes in current shape. <code>(dir)</code> is x or y (or 1, or 2, R, or Z if axisymmetric) to specify the direction of the applied force. <code>(value)</code> is the applied force (in <a href="#units">force units</a>). It can be specified by a number or by a <a href="#function">user-defined function</a> of nodal point position.</li>

<li><a name="stress"></a><code>Stress (dir),(stress1),&lt;stress2&gt;,&lt;(stress3)&gt;</code><br>
Apply stress boundary conditions to faces of elements in the <a href="#fixline">current line</a>, which must have been selected using a <a href="#path">path ID</a>. <code>(dir)</code> is &quot;n&quot; (or 1) or &quot;t&quot; (or 2) for stress to be normal to the edge or tangential; the later is positive when loading the element face in the counter-clockwise direction. <code>(stress1),&lt;stress2&gt;,&lt;(stress3)&gt;</code> are 1 to 3 stresses (in <a href="#units">pressure units</a>). Give one stress for constant stress, two stresses for linear variation in stress along the edge, or three stresses for a quadratic variation in stress.</li>

<li><a name="rotate"></a><code>Rotate (axis),(angle)</code><br>
Rotate nodes in current shape for the purpose of applying skewed displacement boundary conditions.
<code>(axis)</code> must be z (or 3). <code>(angle)</code> is the clockwise angle (in degrees).</li>

<li><a name="select"></a><code>Select</code><br>
Select the nodes and/or elements reference by the current <a href="#fixline">FixLine</a> or <a href="#fixpoint">FixPoint</a> boundary condition for conditional <a href="#output">output</a> of results.</li>

<li><a name="selectline"></a><code>SelectLine (x1OrID),&lt;(y1)&gt;,&lt;(x2)&gt;,&lt;(y2)&gt;,&lt;(tol)&gt;</code><br>
Select all nodes on a line for conditional <a href="#output">output</a> of results. If only <code>(x1OrID)</code> is given, it must be a <a href="#path">path ID</a>. If more parameters are given,  select all nodes along the line from <code>(x1,y1)</code> and <code>(x2,y2)</code> with optional tolerance <code>(tol)</code> (all in <a href="#units">length units</a>).</li>

<li><a name="selectpoint"></a><code>SelectPoint (xOrID),&lt;(y)&gt;</code><br>
Select one node for conditional <a href="#output">output</a> of results. If only <code>(xOrID)</code> is given, it must be a <a href="#keypoint">key point ID</a> and that node is selected. If <code>(y)</code> is provided, <code>(xOrID,y)</code> defines coordinates (in <a href="#units">length units</a>) for a point and the one node nearest to that point is selected.</li>

<li><code>Periodic (axis),&lt;(constraint,value)&gt;,...</code><br>
Set up calculations to be periodic in the (axis) direction (x, y, or Z (if axisymmetric)). Up to two <code>(constraint)</code> settings can be "Delta" or "Slope" ("Shear" is equivalent to slope).
There corresponding values impose that constraint on the periodic analysis. A "Delta" value gives a displacement jump (in <a href="#units">length units</a>) along the
periodic axis and defines the average strain in that direction. When only one direction is periodic, a "Slope" value impose rotation of one edge compared to the other.
When both directions are periodic, a "Shear" value imposes average shear strain.</li>

</ul>

<p>|<a href="#cindex">Documentation Index</a>|</p>

<h2><a name="gravity"></a>Gravity in MPM Calculations</h2>

<p>This command can add gravity or other body forces to an MPM simulation:</p>

<ul>

<li><code>Gravity &lt;(ax)&gt;,&lt;(ay)&gt;,&lt;(az)&gt;</code><br>
Apply body forces to all particles for simulations within a constant gravitational field
where <code>(ax)</code>, <code>(ay)</code>, and <code>(az)</code> are the accelerations due to gravity (in <a href="#units">acceleration units</a>) in the x, y, and z
directions, respectively (<code>(ax)</code> and <code>(ay)</code> are for R and Z directions in axisymmetric calculations). If any parameters or omitted, they are set to default values of (0,-9806.65 mm/sec<sup>2</sup>,0) in Legacy mode or (0,-9.80665 <a href="#units">acceleration units</a>,0) in consistent units mode. If no Gravity command is used, there is no gravity.<br>
&nbsp;&nbsp;&nbsp;&nbsp;Any of the parameters can alternatively be a <a href="#function">user-defined function</a> of x, y, and z (in <a href="#units">length units</a>) and t (in <a href="#units">alt time units</a>) to give position and/or time dependent body forces (in <a href="#units">acceleration units</a>).</li>

</ul>

<p>|<a href="#cindex">Documentation Index</a>|</p>



<h2><a name="custom"></a>Custom Tasks</h2>

<p>These commands are used to schedule custom tasks that are run at the end of each time step
in MPM calculations.</p>

<ul>
<li><code>CustomTask (name)</code><br>
Schedule a custom task with name in <code>(name)</code>.
</li>

<li><code>Parameter (arg),&lt;(value)&gt;</code><br>
Add parameter with name <code>(arg)</code> to the current custom task with value <code>(value)</code>, which is optional because some
custom task parameters do not take a value.
</li>

</ul>

<p>The currently available (and documented) custom tasks and their parameters are:</p>

<ul>
<li><a href="#XPICFMPM">PeriodicXPIC</a>: to run simulations using XPIC(k) or FMPM(k).</li>
<li><a href="#VTKArchive">VTKArchive</a>: to archive results extrapolated to the grid in &quot;VTK Legacy&quot; files.</li>
<li><a href="#HistoryArchive">HistoryArchive</a>: archive material history data to a tab-delimited file.</li>
<li><a href="#ReverseLoad">ReverseLoad</a>: monitor crack length and perform actions when a specified crack length is reached.</li>
<li><a href="#AdjustTimeStep">AdjustTimeStep</a>: adjust time step, if needed, during the calculation</li>
<li><a href="#CustomThermalRamp">ThermalRamp</a>: apply property to all particles over a ramp</li>
<li><a href="#unknown">Undocumented Custom Tasks</a>: you can attach custom tasks that are in <code>NairnMPM</code> but not known here to <b>NairnFEAMPM</b>, such as user-written custom tasks.</li>
</ul>



<h3><a name="XPICFMPM">PeriodicXPIC</a></h3>

<p>The XPIC(k) and FMPM(k) methods are advanced methods that filter out unwanted noise (in the null space) without damping out useful information. Many simulations can benefit by running them using XPIC(k) or FMPM(k). This custom tasks lets you add XPIC(k) or FMPM(k) to any simulation and select the frequency of those calculations. The parameters are:</p>

<ul>
<li>FMPMOrder,(order) - Select the order <code>k</code> and use FMPM(k) in the simulations.</li>
<li>XPICOrder,(order) - Select the order <code>k</code> and use XPIC(k) in the simulations.</li>
<li>periodicSteps,(steps) -Select the number of steps between time steps using XPIC(k) or FMPM(k).</li>
<li>periodicTime,(time) - Select the time interval between time steps using XPIC(k) or FMPM(k) (in <a href="consistentunits.html#units">alt time units</a>).</li>
<li>periodicCFL,(CFL) - Select the time interval based on a CFL factor between time steps using XPIC(k) or FMPM(k).</li>
<li>verbose,(option) - If a non-zero integer, a comment line is printed in the output file every time FMPM(k) or XPIC(k) time steps are done. The default is 0.</li>
<li>GridBCOption,(style) - Use "lumped" to use lumped mass matrix methods for boundary conditions, "velocity" to only impose grid velocity conditions in the velocity field, or "combined" to do both. The default is "combined" for FMPM(k) and "lumped" for XPIC(k). Note that XPIC(k) cannot use "velocity" option. This option only affects calculations when order <code>k</code> is greater than 1.</li>
</ul>

<p>If periodicSteps is set, it is used and the other two are ignored. If periodicSteps is not used, the time step is found from the periodicCFL value (if provided) or from periodicCFL value. One of these three parameters is required to enable periodic FMPM(k) or XPIC(k) calculations.</p>

<p>Additional PeriodicXPIC parameters set add FMPM(k) options to conduction and diffusion calculations. Those types of calculations are still in developed. To use the commands see help on <a href="http://osupdocs.forestry.oregonstate.edu/index.php/PeriodicXPIC_Custom_Task">OSUPDocs</a>.
</p>

<h3><a name="VTKArchive"></a>VTKArchive</h3>

<p>This task allows <code>NairnMPM</code> to export data extrapolated to the grid during the calculation to VTK Legacy files (these files can be visualized by other software such as <a href="http://www.paraview.org" target="new">Paraview</a>). The parameters define what is saved in the files:</p>

<ul>

<li>mass - nodal mass (in <a href="#units">mass units</a>). This option is needed for creating contours that visualize the boundaries of the object. Note that mass is always archived; you do not need to specify it.</li>
<li>material - the material number to visualize different materials in a composite.</li>
<li>displacement - the displacement vector (in <a href="#units">length units</a>).</li>
<li>velocity - the velocity vector (in <a href="#units">velocity units</a>).</li>
<li>stress - the stress tensor (in <a href="#units">pressure units</a>).</li>
<li>pressure - the pressure (in <a href="#units">pressure units</a>).</li>
<li>equivstress - the equivalent stress (also know as von Mises stress) (in <a href="#units">pressure units</a>).</li>
<li>defgrad - the deformation gradient (absolute).</li>
<li>totalstrain - the total <a href="#biot">Biot</a> strain tensor (absolute).</li>
<li>elasticstrain - the elastic <a href="#biot">Biot</a> strain tensor (absolute, can use "strain" as well).</li>
<li>plasticstrain - the plastic <a href="#biot">Biot</a> strain tensor (absolute).</li>
<li>deltav - the relative volume change (V-V<sub>0</sub>)/V<sub>0</sub> (absolute).</li>
<li>equivstrain - the equivalent strain from above total <a href="#biot">Biot</a> strain (absolute).</li>
<li>temperature - the temperature (in K).</li>
<li>concentration - the concentration (in wt %).</li>
<li>strainenergy - the strain energy (in <a href="#units">energy units</a>, can be "workenergy" as well).</li>
<li>heatenergy - the heat energy (in <a href="#units">energy units</a>).</li>
<li>plasticenergy - the plastic energy (in <a href="#units">energy units</a>).</li>
<li>contactforce - the nodal force on the grid for <code>MultiMaterialMode</code> simulations
when they include rigid materials that have <code>SetDirection</code>=8. It is force of the rigid material on the object in <a href="#units">force units</a>.</li>
<li>volumegradient,(mat) - the volume gradient used for contact calculations when running in multimaterial model.
The (mat) argument is the material ID whose gradient is archived.</li>
<li>numpoints - the number of material points interacting with each node in the grid.</li>
<li>archiveTime,(time) - enter the time interval (in <a href="#units">alt time units</a>) between saving of <code>VTK</code> archives. If this parameter is omitted, the VTK archive files are written on the same steps as the particle archives.</li>
<li>firstArchiveTime,(time) - enter the time to save the first results (in <a href="#units">alt time units</a>). This parameter is ignored unless archiveTime has be set as well.</li>
<li>selectMaterial,(matnum) - selects a material (by material number only) to archive grid results only from that material. You can use multiple <code>VTKArchive</code> custom tasks to output different materials. The default is to omit this parameter and export from all materials.</li>
</ul>

<p><a name="biot">Note:</a> when archiving strains, they are calculated as a Biot strain in the current configuration.
The Biot strain is defined is <B>V-I</B> where <B>V</B> is the left-stretch tensor.
This strain is also the Seth-Hill strain with m=1/2 in current configuration.
For small strain problems it is equivalent to the small strain tensor.
</p>

<h3><a name="HistoryArchive"></a>HistoryArchive</h3>

<p>This custom task provides a method to archive more history variables and also provides an alternate format for archiving history variables 1 through 4. When this task is activated, the history data on each particle will be written to tab-delimited text files in the output results folder. You select which history variables to archive, and their order, using a series of <code>Parameter</code> commands:</p>
<pre>Parameter,(number)
</pre>
<p>where the (number) is the history variable number. Two other parameters are:<p>

<ul>
<li>archiveTime,(time) - enter the time interval (in <a href="#units">alt time units</a>) between saving of history archives. If this parameter is omitted, the history archive files are written on the same steps as the particle archives.</li>
<li>firstArchiveTime,(time) - enter the time to save the first history results (in <a href="#units">alt time units</a>).</li>
</ul>

<h3><a name="ReverseLoad"></a>ReverseLoad</h3>

<p>This custom task monitors crack lengths or any currently archived <a href="#globalarchive">global quantity</a>. To monitor crack lengths, enter the following parameters:</p>

<ul>
<li>maxLength,(length) - this parameter specifies the maximum crack length (in <a href="#units">length units</a>). Once this length is reached, the specified task action is triggered.</li>

<li>crackNumber,(num) - this parameter gives the crack number to watch. When that crack reaches the specified maximum length, the task action will be triggered. Alternatively, <code>crackNumber</code> can be zero which causes the task action to trigger when any crack reaches the specified maximum length. The default value is 0 (or any crack).</li>
</ul>

<p>Alternatively, to trigger task action on a <a href="#globalarchive">global quantity</a>, enter the following parameters:</p>

<ul>
<li>quantity,(quantity) - specify the <a href="#globalarchive">global archive quantity</a> by name (<i>e.g.</i>, "sxx"). The use of this parameter converts the task to trigger on critical value of a global quantity rather then a crack length.</li>

<li>material,(mat) - if the global archive being used as a trigger is for a specific material or a boundary condition ID, enter that material (by material ID) or the boundary condition ID (number less than zero) in this parameter.</li>

<li>maxValue,(value) - this parameter specifies the critical value for the global quantity. If the value is positive, the trigger happens when the quantity first exceeds this value; if it is negative, the trigger happens when the quantity becomes more negative than this value.</li>
</ul>

<p>When this task is triggered by critical crack length, the crack propagation will stop and then the task action will take affect. When the trigger is a global quantity, reaching the critical value will trigger the action (but crack propagation will be unaffected). The possible task actions after the trigger are set with the following parameters:</p>

<ul>
<li>style,(mode) - the (mode) option determines what happens after the task is triggered. The default value is 0. The options are:
<ul class="lev2args">
<li>0: Reverses all linearly increasing particle loads, particle tractions, and constant-velocity rigid particles and stop when they return to zero.</li>
<li>1: Stops all linearly increasing particle loads and tractions at their current value and zeros the velocity of all constant-velocity rigid particles. The analysis continues.
</li>
<li>2: All particle loads and tractions and rigid particles continue unchanged. Only the crack propagation stops. This option is meaningless and therefore not allowed when the task is triggered on a global quantity.
</li>
<li>3: The analysis terminates.
</li>
</ul></li>
<li>hold,(holdTime) - when (holdTime) is positive, the task will hold at current boundary conditions for the specified time (in <a href="#units">alt time units</a>) and then proceed with the style option. A hold phase is only allowed when style is 0 (to reverse) or 3 (to abort).</li>
</ul>

<h3><a name="AdjustTimeStep"></a>AdjustTimeStep</h3>

<p>This tasks allows the time step to change if the wave speed in any material changes (and the material class supports calculation of wave speed as a function of particle state). Its parameters are:</p>

<ul>
<li>adjustTime,(time) - enter the time interval for checking the time step and adjusting it if needed (in <a href="#units">alt time units</a>). This parameter is optional; if it is omitted, the time step adjustment is done each time particle data are archived.</li>
<li>verbose,(value) - if its integer value is not zero, it will print the new time step whenever it changes by more than 1%. If it is zero, the new time step is silently changed. The default it 0.</li>
</ul>

<h3><a name="CustomThermalRamp"></a>ThermalRamp</h3>

<p>This tasks ramps a temperature, concentration, or pore pressure applied to all particles. A simulation can combine multiple thermal ramps for various styles of applying the selected property. Its parameters are:</p>

<ul>
<li>property,(prop) - 0 to ramp particle temperature. 1 is reserved for future use. 2 to ramp particle concentration. For <a href="#conc">diffusion calculations</a>, this option will ramp particle concentration potential (between 0 and 1). For <a href="#poro">poroelasticity calculations</a>, this option will ramp particle pore pressure (in <a href="#units">pressure units</a>).</li>
<li>time,(time) - enter the time of the ramp (in <a href="#units">alt time units</a>). This parameter is optional; if omitted, the ramp occurs in a single time step.</li>
<li>start,(start) - enter the time to start the ramp (in <a href="#units">alt time units</a>). This parameter is optional; if omitted, the ramp starts at time zero. It ends at time (start)+(time)</li>
<li>sigmoidal,(style) - enter 0 or 1 for a linear or sigmoidal ramp. This parameter is optional; if omitted, the ramp is linear.</li>
</ul>

<p>The above parameters create a ramp. The next commands determine the magnitude of the particle property applied during the ramp:</p>

<ul>
<li>DeltaT,(deltaT) - enter final temperature difference (in K), concentration potential, or pore pressure (in <a href="#units">pressure units</a>).</li>
<li><code>scale,(function)</code> - if this optional command is used, the applied <code>DeltaT</code> is scaled by any <a href="#function">user-defined function</a> of time and particle position. The <code>(function)</code> must be embedded in the parameter name (<i>e.g.</i>, <code>"scale x/40"</code>).</li>
</ul>

<p>Besides the above thermal ramp, this task can ramp thermal fields provided in bit mapped files and ramp other quantities (such as out-of-plane stress and strain, particle concentration, or particle pore pressure). These options are documented only in the <a href="http://osupdocs.forestry.oregonstate.edu/index.php/ThermalRamp_Custom_Task">OSUPDocs wiki</a>. 
</p>

<h3><a name="unknown"></a>Undocumented Custom Tasks</h3>

<p>Other custom tasks may be written for NairnMPM (or OSParticulas) but not known to this help information. You can find the lastest available tasks in the <a href="http://osupdocs.forestry.oregonstate.edu/index.php/MPM_Input_Files#Custom_Tasks">OSUPDocs wiki on Custom Tasks</a>. You can still use such tasks. Enter the name of the task (exactly as specified and case sensitive) in the
<code>CustomTask</code> command and then follow that with any number of <code>Parameter</code> commands. The
parameter names and their values are passed exactly as provided (case sensitive) to the input file (including text
values) and should match the requirements of the undocumented task.</p>

<p>|<a href="#cindex">Documentation Index</a>|</p>

<h2><a name="xml"></a>XML Commands</h2>

<p>These commands are used to insert raw <code>XML</code> commands at various locations in the input commands. See Code Engine Commands for the format of all raw <code>XML</code> commands.</p>

<ul>

<li><code>Entity (entity),(def)</code><br>
Define entity to appear in XML output file. <code>(entity)</code> is the entity name without ampersand and semicolon and <code>(def)</code> is its definition. Some other commands can use entities for their values.</li>

<li><a name="xmldata"></a><code>XMLData &lt;(where)&gt;,&lt;(mat)&gt;<br>
&nbsp;&nbsp;(lines of verbatim XML content)<br>
EndXMLData</code><br>
Insert XML data in the interpretation output. <code>(where)</code> indicates the section where the XML content will be inserted and it will be at the end of that section (unless otherwise noted). The options are:
<ul>
<li><code>&quot;Header&quot;</code></li>

<li><code>&quot;MPMHeader&quot;</code> (MPM only)</li>

<li><code>&quot;Mesh&quot;</code></li>

<li><code>&quot;MaterialPoints&quot;</code> to intersperse with other commands in this section (MPM only)</li>

<li><code>&quot;CrackList&quot;</code> to intersperse with other crack definitions &mdash; the XML data must
define a complete crack but omit the enclosing <code>&lt;CrackList&gt;</code> element
(it is inserted automatically) (MPM only)</li>

<li><code>&quot;Materials&quot;</code> to intersperse a custom material definition (see below)</li>

<li><code>&quot;GridBCs&quot;</code> to intersperse with other commands in this section</li>

<li><code>&quot;ParticleBCs&quot;</code> (MPM Only)</li>

<li><code>&quot;Thermal&quot;</code></li>

<li><code>&quot;Gravity&quot;</code> (MPM Only)</li>

<li><code>"CustomTasks"</code> (MPM Only)</li>

</ul>
If <code>(where)</code> is omitted (or is "<code>End</code>"), the XML content is inserted at the end of the XML commands. If <code>(where)</code> is &quot;Material&quot;, the XML content is assumed to completely define a single material. This content is inserted (in definition order) among other materials and <code>(mat)</code> must define the <a href="#material">material ID</a>, which can then be referenced in other commands.</li>

</ul>

<p>|<a href="#cindex">Documentation Index</a>|</p>

<h2><a name="deprecate"></a>Deprecated Commands</h2>

<p>The commands listed below have been deprecated. Unless otherwise mentioned, these commands still work, but they should be avoided (and replaced with the new option instead). They may eventually stop working or be permanently removed from supported command options.</p>

<h3>Multimaterial Mode Commands</h3>

<p>These following commands are for old methods used for crack settings. They have been replaced by <a href="#mmmode">new methods</a> and contact laws.</p>

<ul>

<li><a name="frictmm"></a><code>FrictionMM (frict)</code><br>
Set default multimaterial mode friction properties where (first) sets it as explained in the <a href="#frict">Friction command</a>. Replace with <a href="#mmode">ContactMM</a> command.</li>

<li><a name="imperfectmm"></a><code>ImperfectInterfaceMM (Dt),(Dn),&lt;(Dnc)&gt;</code><br>
Set default properties for material contact to model an imperfect interface. The parameters are entered as explained in the <a href="#imperfect">ImperfectInterface command</a>. Replace with <a href="#mmode">ContactMM</a> command.</li>

<li>See also <a href="#matprops">deprecated material properties</a> that used to set custom contact between two specific material types.</li>

</ul>

<h3><a name="crackcontact"></a>Crack Contact Commands</h3>

<p>These following commands are for old methods used for crack options. They have been replaced by <a href="#cracks">new methods</a> for cracks and crack contact.</p>

<ul>
<li><a name="frict"></a><code>Friction (frict)</code><br>
Set default crack contact friction properties with options:
<ul>
<li>number - the friction coefficient</li>
<li>&quot;stick&quot; - to use stick contact</li>
<li>&quot;single&quot; (or &quot;ignore&quot;) - to revert to single velocity field</li>
<li>&quot;none&quot; - for frictionless contact (same as 0 and it is the default)</li>
</ul>
Replace with <a href="#csettings">ContactCracks</a> command.
</li>

<li><a name="imperfect"></a><code>ImperfectInterface (Dt),(Dn),&lt;(Dnc)&gt;</code><br>
Set default properties for crack surfaces to model an imperfect interface. <code>(Dt)</code> and <code>(Dn)</code> are the D<sub>t</sub> and D<sub>n</sub> interface parameters for tangential and normal traction (in <a href="#units">pressure units/length units</a>). If (Dnc) is given, it is the normal interface parameter for compression and (Dn) is converted to be the normal interface parameter for tension. Any parameter can by -1 to indicate a prefect interface in that direction. Replace with <a href="#csettings">ContactCracks</a> command.</li>

<li><code>CrackInterface (Dt),(Dn),&lt;(Dnc)&gt;</code><br>
Used after a <a href="#cracks">new crack</a> definition, this command sets current crack to use custom imperfect interface properties. The parameters are the same as in the <a href="#imperfect">ImperfectInterface command</a>. Replace by using <code>(lawid)</code> parameter in a <a href="#cracks">NewCrack command</a>.</li>

</ul>

<h3><a name="bcs"></a>Boundary Condition Blocks</h3>

<p>The following commands for grid boundary conditions involve one specific type of shape. They should be replaced by a <a href="#bconds">GridBC block</a>. See each command for details on the replacement command (noting some changes in order of parameters).</p>

<ul>

<li><code>MoveLine (x1),(y1),(x2),(y2),&lt;tol&gt; ... EndMoveLine</code><br>
Replace with block that uses a line shape:<br>
<code>GridBC<br>
&nbsp;&nbsp;Line (x1),(x2),(y1),(y2),&lt;tol&gt;<br>
&nbsp;&nbsp;(grid condition commands)<br>
EndGridBC</code>
</li>

<li><code>MoveArc (x1),(y1),(x2),(y2),(start),(end),&lt;(tol)&gt; ... EndMoveArc</code><br>
Replace with block that uses a arc shape:<br>
<code>GridBC<br>
&nbsp;&nbsp;Arc (x1),(x2),(y1),(y2),&lt;tol&gt;<br>
&nbsp;&nbsp;(grid condition commands)<br>
EndGridBC</code>
</li>

<li><code>MoveBox (x1),(y1),(z1),(x2),(y2),(z2),&lt;(axis)&gt; ... EndMoveBox</code><br>
Replace with block that uses a box shape:<br>
<code>GridBC<br>
&nbsp;&nbsp;Box (x1),(x2),(y1),(y2),(z1),(z2)<br>
&nbsp;&nbsp;(grid condition commands)<br>
EndGridBC</code>
</li>

</ul>

<p>The following commands for particle boundary conditions involve one specific type of shape. They should be replaced by a <a href="#bconds">ParticleBC block</a>. See each command for details on the replacement command (noting some changes in order of parameters).</p>

<ul>

<li><code>LoadLine (x1),(y1),(x2),(y2),&lt;tol&gt; ... EndLoadLine</code><br>
Replace with block that uses a line shape:<br>
<code>ParticleBC<br>
&nbsp;&nbsp;Line (x1),(x2),(y1),(y2),&lt;tol&gt;<br>
&nbsp;&nbsp;(grid condition commands)<br>
ParticleBC</code>
</li>

<li><code>LoadRect (xmin),(xmax),(ymin),(ymax) ... EndLoadRect</code><br>
Replace with block that uses a rect shape:<br>
<code>ParticleBC<br>
&nbsp;&nbsp;Rect (xmin),(xmax),(ymin),(ymax)<br>
&nbsp;&nbsp;(grid condition commands)<br>
ParticleBC</code>
</li>

<li><code>LoadArc (x1),(y1),(x2),(y2),(start),(end),&lt;(tol)&gt; ... EndLoadArc</code><br>
Replace with block that uses a arc shape:<br>
<code>ParticleBC<br>
&nbsp;&nbsp;Arc (x1),(x2),(y1),(y2),&lt;tol&gt;<br>
&nbsp;&nbsp;(grid condition commands)<br>
ParticleBC</code>
</li>

<li><code>LoadBox (x1),(y1),(z1),(x2),(y2),(z2),&lt;(axis)&gt; ... EndLoadBox</code><br>
Replace with block that uses a box shape:<br>
<code>ParticleBC<br>
&nbsp;&nbsp;Box (x1),(x2),(y1),(y2),(z1),(z2)<br>
&nbsp;&nbsp;(grid condition commands)<br>
ParticleBC</code>
</li>

</ul>


<h3><a name="matprops"></a>Material Properties</h3>

<p>The following properties are deprecated material properties. They should be replaced by the indicate new property:</p>

<ul>

<li><code>Friction (frict),(mat)</code> - a <a href="#frict">Friction command</a> within a material definition can define custom frictional properties for <a href="#mmmode">multimaterial mode MPM</a> contact between the current material
and another material (specified in <code>(mat)</code>). Use the <a href="materials.html#cmn4"><code>Contact</code></a> material property instead.</li>

<li><code>Interface (Dt),(Dnt),(Dnc),(matid)</code> - an <a href="#imperfect">Interface command</a> within a material definition can define custom imperfect interface parameters properties for <a href="#mmmode">multimaterial mode MPM</a> contact between the
current material and another material (specified in <code>(mat)</code>). Use the  <a href="materials.html#cmn4"><code>Contact</code></a> material property instead.</li>

</ul>


<h2><a name="function"></a>User-Defined Functions</h2>

<p>When a user-defined function option is allowed in any command, you can enter any valid function of the following variables when doing MPM simulations:</p>

<ul>
<li><code>x</code> - x position in <a href="#units">length units</a></li>
<li><code>y</code> -  y position in <a href="#units">length units</a></li>
<li><code>z</code> -  z position in <a href="#units">length units</a></li>
<li><code>t</code> - current time in <a href="#units">alt time units</a></li>
<li><code>dt</code> - the time step in <a href="#units">alt time units</a></li>
<li><code>q</code> - particle rotation in radians about the z (or &theta; if axisymmetric) axis</li>
</ul>

<p>For FEA calculations, the following variables are allowed and may refer to position of element centroid or node depending on the command:</p>

<ul>
<li><code>x</code> - x position in <a href="#units">length units</a></li>
<li><code>y</code> -  y position in <a href="#units">length units</a></li>
<li><code>r</code> - radial position of axisymmetric calculations in <a href="#units">length units</a> (synonym for <code>x</code>)</li>
<li><code>z</code> -  axial position of axisymmetric calculations in <a href="#units">length units</a> (synonym for <code>y</code>)</li>
</ul>

<p>When a function is used, it will be calculated using these variables and should return a result in the units expected by the command.
Note that commands that allow functions may only allow a subset of these variables (due to command context). You can refer to each command for the allowed variables. For example, some MPM options require the function to depend <i>only</i> on time. Particle-based MPM boundary conditions let the function depend on clockwise particle rotational angle <tt>q</tt> about the <code>z</code> axis (in radians), which allows rotation of the boundary conditions with the particle. Note that <tt>q</tt> is particle rotation since the start of the simulation and will differ from material angle if the particle started with a non-zero orientation angle (<i>i.e.</i>, the current material angle is the sum of <code>q</code> and its initial angle).</p>

<p>When setting up MPM simulations or FEA calculations, a few more variables are sometimes allowed:</p>

<ul>
<li><code>R</code> - radial position in <a href="#units">length units</a> for axisymmetric calculation; <code>R</code> is a synonym for <code>x</code>, which also works</li>
<li><code>Z</code> - axial position in <a href="#units">length units</a> for axisymmetric calculation; <code>Z</code> is a synonym for <code>y</code>, which also works</li>
<li><code>D</code> - distance from origin in <a href="#units">length units</a></li>
<li><code>T</code> - counter-clockwise angle (in radians) from the positive x axis  (<i>i.e.</i>, &theta; in polar coordinates)</li>
</ul>

<p>Here <code>(R,Z)</code> are axisymmetric coordinates and <code>(D,T)</code> are polar coordinates, where <code>D</code> is distance from the origin to the <code>(x,y)</code> (or <code>(R,Z)</code> if axisymmetric) point and <code>T</code> is counter-clockwise angle from the positive <code>x</code> (or <code>R</code> if axisymmetric) axis to the point. These extra variables are only allowed in:
</p>

<ul>
<li><a href="#regionmpm">MPM Region commands</a> to set initial particle velocity, angular momentum, or rotation angle.</li>
<li><a href="#regionfea">FEA Region commands</a> to set initial material angle.</li>
<li><a href="#area">FEA Area Commands</a> to set initial material angle.</li>
<li><a href="#thermalfea">FEA Temperature commands</a> to set initial temperature on the nodes.</li>
</ul>

<p>Some details on entering functions are:</p>

<ul>

<li>The function must be enclosed in quotes (<i>e.g.</i>, &quot;<code>x^2+y^2</code>&quot;) to prevent it from being evaluated as a <a href="#varexp">command expression</a> prior to being used in the analysis.
</li>

<li>Enter variables simply as <code>x</code>, <code>y</code>, <i>etc.</i>, and not with the preceding &quot;<code>#</code>&quot; used for <a href="#varexp">command expression variables</a>.
</li>

<li>Operators: The function uses standard operators + - * / and ^ with standard operator precedence for addition, subtraction, multiplication, division, and raising to a power.
</li>

<li>The function can contain use any <a href="#numexprs">numeric expression</a> supported in the scripting language.</li>

<li>Functions can include <code>pi</code> (or <code>Pi</code> or <code>PI</code>) for the number &pi;.
</li>

<li>Exponential Notation: numbers can have &quot;<code>e</code>&quot; or &quot;<code>E</code>&quot; for powers of ten such as <code>1.4e3</code> for <code>1400</code>.
</li>

<li>Extra spaces in the function are ignored.
</li>
</ul>

<p>|<a href="#cindex">Documentation Index</a>|</p>

<h2><a name="units"></a>Units Options</h2>

<p>The following table lists possible units needed for entering parameters. The first column gives the name and its definition in terms of length (L), mass (M), time (T), and degrees Kelvin (K). The second column lists how to enter those terms in  Legacy units mode. The third column lists SI or kg-m-s units. The remaining columns give consistent units for various units modes (you are not limited to these modes). To get property in selected units mode, multiply SI-units property by factor in column for that mode. The "Alt" units entries only differ from their normal units when using Legacy mode.</p>

<table border="1" cellpadding="2" cellspacing="0" width="90%" align="center">

<tr><th>Unit</th><th>Legacy</th><th>SI (kgms)</th><th>mmgs</th><th>cgs</th><th>mmgms</th>
</tr>

<tr><td>Length (L)</td><td>mm</td><td>m</td><td>x10<sup>3</sup>=mm</td><td>x10<sup>2</sup>=cm</td><td>x10<sup>3</sup>=mm</td>
</tr>

<tr><td>Mass (M)</td><td>g</td><td>kg</td><td>x10<sup>3</sup>=g</td><td>x10<sup>3</sup>=g</td><td>x10<sup>3</sup>=g</td>
</tr>

<tr><td>Time (T)</td><td>s</td><td>s</td><td>s</td><td>s</td><td>x10<sup>3</sup>=ms</td>
</tr>

<tr><td>Alt Time</td><td>ms</td><td>s</td><td>s</td><td>s</td><td>x10<sup>3</sup>=ms</td>
</tr>

<tr><td>Density (M/L<sup>3</sup>) </td><td>g/cm<sup>3</sup></td><td>kg/m<sup>3</sup></td><td>x10<sup>-6</sup>=g/mm<sup>3</sup></td><td>x10<sup>-3</sup>=g/cm<sup>3</sup></td><td>x10<sup>-6</sup>=g/mm<sup>3</sup></td>
</tr>

<tr><td>Velocity (L/T)</td><td>mm/s</td><td>m/s</td><td>x10<sup>3</sup>=mm/s</td><td>x10<sup>2</sup>=cm/s</td><td>m/s</td>
</tr>

<tr><td>Alt Velocity</td><td>m/s</td><td>m/s</td><td>x10<sup>3</sup>=mm/s</td><td>x10<sup>2</sup>=cm/s</td><td>m/s</td>
</tr>

<tr><td>Acceleration (L/T<sup>2</sup>)</td><td>mm/s<sup>2</sup></td><td>m/s<sup>2</sup></td><td>x10<sup>3</sup>=mm/s<sup>2</sup></td><td>x10<sup>2</sup>=cm/s<sup>2</sup></td><td>x10<sup>-3</sup>=mm/ms<sup>2</sup></td>
</tr>

<tr><td>Force (F=M-L/T<sup>2</sup>)</td><td>N</td><td>N</td><td>x10<sup>6</sup>=&mu;N</td><td>x10<sup>5</sup>=dyne</td><td>N</td>
</tr>

<tr><td>Pressure (P=F/L<sup>2</sup>=M/(L-T<sup>2</sup>))</td><td>MPa</td><td>Pa</td><td>Pa</td><td>x10=Ba</td><td>x10<sup>-6</sup>=MPa</td>
</tr>

<tr><td>Linear Momentum (M-L/T)</td><td>N-s</td><td>N-s</td><td>x10<sup>6</sup>=&mu;N-s</td><td>x10<sup>5</sup>=dyne-s</td><td>x10<sup>3</sup>=N-ms</td>
</tr>

<tr><td>Alt Strain</td><td>%</td><td>none</td><td>none</td><td>none</td><td>none</td>
</tr>

<tr><td>Energy (E=F-L=M-L<sup>2</sup>/T<sup>2</sup>)</td><td>J</td><td>J</td><td>x10<sup>9</sup>=nJ</td><td>x10<sup>7</sup>=erg</td><td>x10<sup>3</sup>=mJ</td>
</tr>

<tr><td>Alt Energy</td><td>&mu;J</td><td>J</td><td>x10<sup>9</sup>=nJ</td><td>x10<sup>7</sup>=erg</td><td>x10<sup>3</sup>=mJ</td>
</tr>

<tr><td>Torque (F-L=M-L<sup>2</sup>/T<sup>2</sup>)</td><td>J</td><td>J</td><td>x10<sup>9</sup>=nJ</td><td>x10<sup>7</sup>=erg</td><td>x10<sup>3</sup>=mJ</td>
</tr>

<tr><td>Angular Momentum (M-L<sup>2</sup>/T)</td><td>J-s</td><td>J-s</td><td>x10<sup>9</sup>=nJ-s</td><td>x10<sup>7</sup>=erg-s</td><td>x10<sup>6</sup>=&mu;J-s</td>
</tr>

<tr><td>Energy Release (E/L<sup>2</sup>=M/T<sup>2</sup>)</td><td>J/m<sup>2</sup></td><td>J/m<sup>2</sup></td><td>x10<sup>3</sup>=mJ/m<sup>2</sup></td><td>x10<sup>3</sup>=erg/cm<sup>2</sup></td><td>x10<sup>-3</sup>=kJ/m<sup>2</sup></td>
</tr>

<tr><td>Stress Intensity (P-L<sup>0.5</sup>=M/(L<sup>0.5</sup>-T<sup>2</sup>))</td><td>MPa-m<sup>0.5</sup></td><td>Pa-m<sup>0.5</sup></td><td>x31.623=Pa-mm<sup>0.5</sup></td><td>x10<sup>2</sup>=Ba-cm<sup>0.5</sup></td><td>x3.1623e<sup>-5</sup>=MPa-mm<sup>0.5</sup></td>
</tr>

<tr><td>Viscosity (P-T=M/(L-T))</td><td>cPoise</td><td>Pa-s</td><td>Pa-s</td><td>x10=Poise</td><td>x10<sup>-3</sup>=kPa-s</td>
</tr>

<tr><td>Diffusion (L<sup>2</sup>/T)</td><td>mm<sup>2</sup>/s</td><td>m<sup>2</sup>/s</td><td>x10<sup>6</sup>=mm<sup>2</sup>/s</td><td>x10<sup>4</sup>=cm<sup>2</sup>/s</td><td>x10<sup>3</sup>=mm<sup>2</sup>/ms</td>
</tr>

<tr><td>Solvent Flux (M/(L<sup>2</sup>-T))</td><td>kg/(m<sup>2</sup>-s)</td><td>kg/(m<sup>2</sup>-s)</td><td>x10<sup>-3</sup>=g/(mm<sup>2</sup>-s)</td><td>x10<sup>-1</sup>=g/(cm<sup>2</sup>-s)</td><td>x10<sup>-6</sup>=g/(mm<sup>2</sup>-ms)</td>
</tr>

<tr><td>Conductivity (E/(L-K-T)=M-L/(T<sup>3</sup>-K))</td><td>W/(m-K)</td><td>W/(m-K)</td><td>x10<sup>6</sup>=&mu;W/(m-K)</td><td>x10<sup>5</sup>=erg/(cm-K-s)</td><td>x10<sup>-3</sup>=kW/(m-K)</td>
</tr>

<tr><td>Heat Capacity (E/(M-K)=L<sup>2</sup>/(T<sup>2</sup>-K))</td><td>J/(kg-K)</td><td>J/(kg-K)</td><td>x10<sup>6</sup>=&mu;J/(kg-K)</td><td>x10<sup>4</sup>=erg/(g-K)</td><td>J/(kg-K)</td>
</tr>

<tr><td>Heat Flux (E/(T-L<sup>2</sup>)=M/T<sup>3</sup>)</td><td>W/m<sup>2</sup></td><td>W/m<sup>2</sup></td><td>x10<sup>3</sup>=mW/m<sup>2</sup></td><td>x10<sup>3</sup>=erg/(cm<sup>2</sup>-s)</td><td>x10<sup>-6</sup>=MW/m<sup>2</sup></td>
</tr>

<tr><td>Heat of Fusion (E/M=L<sup>2</sup>/T<sup>2</sup>)</td><td>J/kg</td><td>J/kg</td><td>x10<sup>6</sup>=&mu;J/kg</td><td>x10<sup>4</sup>=erg/g</td><td>J/kg</td>
</tr>

</table>
<br>

<p>|<a href="#cindex">Documentation Index</a>|</p>

</body>

</html>